Attaching a diagram to a pull request without slowing the merge

The cost of a diagram in every thread is not the generation, it is the attention. A picture that appears on all 40 pull requests a week becomes wallpaper, and the one that mattered is scrolled past with the rest.

Four triggers earn one. A new service, datastore or queue. A change of dependency direction, where a module that was called now calls. A boundary move, where responsibility crosses from one component to another. And a deletion, because removals are the changes reviewers verify least and regret most.

Refactors inside a module, dependency bumps and test changes do not qualify, however large the diff. The question the diagram answers is what talks to what, so a change that does not alter that has nothing to show.

Datadef does not watch pull requests and does not post comments. The loop is invoked: by you in an editor session, or by a job you own that runs an agent. That is a real limit and worth stating plainly, because tools in this space differ on it and the difference decides who maintains the integration. The reason is the access model rather than a missing feature: a repository connection is read-only by construction, a fine-grained GitHub token with Contents read-only, a GitLab token with read_api, or an Azure DevOps token with Code read. None of those can write a comment.

Mechanically, the agent exports the diagram and attaches the image through the host CLI when it posts the comment. What it should not do is paste the signed export URL, which expires after 15 minutes and will render for the author and nobody else. If the diagram is published, the stable embed URL is a better link than any export, because the comment then shows the current diagram whenever someone reopens the thread.

One sentence next to the image does most of the work: what changed, and what the reviewer is being asked to look at. A picture with no question attached gets a thumbs up rather than a review.

# the agent exports, then posts through the host CLI
# (the signed export URL expires in 15 minutes, so attach the file)
gh pr comment 412 --body-file review-note.md

# review-note.md
# ## Architecture change
# ![after](https://datadef.io/api/embed/acme-platform)
# The ingest API no longer calls billing directly; it publishes to
# events.invoices. Question for review: retry semantics on the consumer.

One repository connection can back several diagrams, one per branch or one per release tag. That is the mechanism that makes a before and after comparison real rather than illustrative: point a second linked diagram at the feature branch, and both pictures come out of the same pipeline, the same file selection and the same drawing standard.

A comparison built that way is legible because the only differences are the ones the branch introduced. Two diagrams drawn by different means, one generated and one hand-drawn a year ago, differ in a hundred cosmetic ways and the reader has to filter all of them before finding the real change.

This works best for infrastructure and service topology changes, where the branch actually contains the declaration: Terraform, Kubernetes manifests, compose files, CI configuration, API specs. A branch whose change lives entirely in application logic often produces not a similar diagram but the same one, because file selection takes at most 40 files in priority order and a change confined to application code does not move the structure fingerprint computed over them, so the sync skips generation and the branch diagram stays exactly where it was. That is a useful signal in itself: the architecture did not move.

A diagram job wired as a required check teaches people to ignore it. The generation takes one to three minutes when it runs at all, it depends on a network call, and its failure mode is a red mark on a pull request whose author did nothing wrong. Within a month someone adds a skip label, and the check becomes theatre.

Comment, do not block. If you want a gate, gate on facts a machine verifies without judgment: that every directory named in the architecture doc exists, that internal links resolve, that the API description still matches the handlers. Leave the picture as information for a human, which is what it is.

The freshness of the main-branch diagram is a separate loop and a cheaper one. Daily sync keeps it current on its own, and a structure fingerprint means commits that changed nothing structural do not redraw anything.

• How to review a Terraform pull request
• Docs checks that belong in CI
• Automate the architecture diagram in CI
• Repo to diagram: a diagram per branch or tag
• Collaboration in Datadef