Keep a CI/CD pipeline diagram up to date when the workflow file changes

Three kinds of change break a pipeline diagram, and all three are routine. A stage is added or reordered, usually a scan or a new test tier. An environment is added or renamed, often when a preview environment appears. A gate moves, most often when a team tightens or loosens who can approve production.

Each of those is a small edit to a YAML file and a large edit to the picture. That asymmetry is what makes hand-maintained pipeline diagrams uneconomical: the person who adds a stage in a two-line diff is not going to open a drawing tool, re-export a PNG, and update four wiki pages.

The measurable version of this problem is the drift window, meaning the time between a change reaching main and the diagram reflecting it. Teams that regenerate on merge have a drift window of minutes. Teams that review diagrams quarterly have a drift window measured in weeks, and the diagram is wrong for most of that period. More on measuring it in documentation drift metrics.

Trigger on the paths that can change the picture, not on every commit. For a GitHub repository that is .github/workflows, plus the deployment manifests and any shared workflow repository you consume. Running the regeneration on every merge to main produces noise and, more importantly, produces churn in a diagram that should be stable.

Regenerate with an agent rather than a template. An assistant connected to the Datadef MCP server has 36 tools available, nine outcome-level ones including create_diagram, edit_diagram, repo_status and repo_refresh, and 27 canvas_* tools for the node-level work, so a post-merge job can ask it to reconcile the existing canvas with what the workflow files now contain. That is an edit to a known diagram, not a fresh drawing each time, which is what keeps the result recognisable.

Publish once and link everywhere. The diagram gets an embed URL, and the README, the wiki page, the onboarding doc, and the incident runbook all point at it. Updating the canvas updates all four with no commits, no attachments, and no stale copies left behind. Viewers need no account to see it.

# .github/workflows/refresh-diagram.yml
on:
  push:
    branches: [main]
    paths:
      - '.github/workflows/**'
      - 'deploy/**'

jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Reconcile the pipeline diagram
        run: |
          # a Claude Code run with the Datadef MCP server configured: it
          # reads the workflow files and calls edit_diagram on the existing
          # canvas, so ids, labels and hand-set positions survive
          claude -p "Update the CI/CD pipeline diagram to match the \
            workflows in .github/workflows. Reuse existing node ids and \
            positions. Report what changed in one paragraph."

Datadef connects to a GitHub, GitLab, or Azure DevOps repository with read-only access, on a branch or a tag of your choosing, and regenerates the diagram along with an architecture document on a daily sync as well as on demand. For infrastructure repositories written in Terraform, every .tf file is parsed directly, without terraform init, without reading state, and without any cloud credentials.

The honest boundary for CI/CD specifically: the deep parse is built for infrastructure code, so a pipeline diagram driven by workflow YAML is best kept current through the agent loop above, where an assistant reads the files and edits the canvas. Repository sync is what keeps the surrounding architecture diagram, the one your pipeline deploys into, true at the same time.

The second is the reading budget. Outside the Terraform path the sync assembles a corpus instead of reading everything: at most 40 files, 250KB in total, 30KB per file with the remainder truncated behind a marker, and a per-class cap so no one directory floods the budget. Under the architecture weighting those caps allow 16 infrastructure files and 10 CI files, which means a repository with 30 workflow files will not have all 30 read. A compact tree summary rides along so the model at least knows what was left out.

The third: Datadef does not watch your repository for events. The trigger is your pipeline's job, exactly like a lint step or a link checker. That is a feature for anyone who does not want a third party holding a webhook on their default branch. Connection details are in the repository sync docs.

Automatic regeneration fails socially long before it fails technically. If every sync reshuffles the canvas, people stop trusting the picture they memorised, and a team that cannot recognise its own diagram will go back to a PNG within a month.

Two properties prevent that, and both are measurable rather than aspirational. The sync hashes what actually feeds the diagram and skips generation entirely when that hash has not moved, so a commit editing a step command, a README, or a test costs zero tokens and produces zero redraw. And a node is treated as hand-moved once it sits more than 12 pixels from where the previous sync left it, at which point its coordinates are restored after the fresh layout, so an untouched diagram stays free to re-lay-out while an arranged one holds still.

When the structure genuinely did change, the previous diagram goes back to the model as context: up to sixty existing nodes with their ids, labels, and zones, plus the rule that anything still present in the source keeps all three. Measured on an Azure infrastructure repository, adding a single resource kept every existing id and label, produced exactly one new node, and left a hand-dragged node on its exact coordinates.

Add one human habit on top: when the regeneration reports a change, read the report rather than the diagram. A one-line summary saying a stage was added and a gate moved is faster to review than a visual diff, and it is the thing worth pasting into the pull request that caused it.

• How to detect stale diagrams
• Documentation checks in CI
• When to regenerate an architecture diagram
• Live embeds
• Repo to diagram