Jenkins pipeline diagram: draw the Jenkinsfile, not the last run

Stage View and the newer Pipeline Graph View render the stages of a completed run with timings and status colours. Blue Ocean did the same thing more prettily and has stopped taking new features, so Pipeline Graph View, which needs Jenkins 2.479.3 or later, is where this view now lives. For diagnosing why last night's build failed, any of them is the right tool and no drawn diagram beats them.

They cannot show the stages that did not execute. A stage guarded by a when clause, a deploy that only runs on the release branch, a cleanup that only runs on failure: all of them are absent from the picture of a run in which they did not fire, and absent in a way the reader cannot detect. The standing map has to come from the file.

They also stop at the job boundary. A multibranch pipeline is a family of jobs, a downstream build triggered with the build step is a separate job with its own view, and a pipeline that calls a shared library step sees that step as a single line. None of those relationships appear in a run view, and all of them belong on a wiki diagram.

Declarative pipelines map to shapes almost one to one. Each stage block is a node. A parallel block is a fan-out and fan-in pair, and its branch names are the node labels. An agent directive, whether at pipeline level or overridden per stage, is a property worth writing on the node, because "runs on the docker-arm64 label" explains failures that stage names never will.

Two constructs deserve gate shapes rather than plain nodes. The input step is a manual approval and should be drawn with its submitter list and timeout, exactly like an approval gate on any other pipeline. A when clause that restricts a stage to a branch or a tag is a condition on the edge into that stage, and writing the condition on the arrow saves the reader a trip to the file.

Post blocks are the part people forget. A post section with always, success, and failure branches is where notifications, cleanup, and artifact archiving live, and on a diagram it is a small cluster hanging off the end rather than another stage in the main line.

@Library('platform-ci@v3') _          // half the steps come from here

pipeline {
  agent { label 'linux-amd64' }       // default node placement
  stages {
    stage('Build') { steps { sh 'make build' } }
    stage('Test') {                    // one fan-out, two branches
      parallel {
        stage('Unit')        { steps { sh 'make test-unit' } }
        stage('Integration') { agent { label 'docker' }
                               steps { sh 'make test-int' } }
      }
    }
    stage('Publish') { steps { publishArtifact() } }   // shared library step
    stage('Approve') {                 // draw this as a gate, not a stage
      steps { input message: 'Deploy to prod?', submitter: 'release-managers' }
    }
    stage('Deploy prod') {
      when { branch 'main' }           // condition belongs on the edge
      agent { label 'prod-egress' }
      steps { deployService(env: 'prod') }
    }
  }
  post { failure { notifySlack() } }   // small cluster off the end
}

A mature Jenkins setup moves most real logic into a shared library, so the Jenkinsfile becomes a list of custom steps. deployService() might resolve credentials, run a helm upgrade, wait for rollout, and post to a channel, and none of that is visible in the pipeline file. A diagram drawn only from the Jenkinsfile will therefore be accurate and useless at the same time.

The fix is to expand the library steps that matter. Read vars/deployService.groovy, decide which of its actions are architecturally interesting (which systems it touches, which credentials it uses), and draw those as a sub-cluster behind the step node. Pin the library version on the diagram too, since @Library('platform-ci@v3') means the drawing is only true for v3.

Multibranch and folder-level configuration are the other half of the invisible surface. Branch discovery rules, folder credentials, and shared environment variables set at folder level change what a pipeline does without changing the Jenkinsfile. Note them as annotations on the diagram rather than pretending the file is the whole story.

A Jenkinsfile changes far more often than the architecture it deploys, which is exactly the condition under which hand-drawn diagrams rot. Two mechanisms keep it current without a person redrawing it.

The first is an agent loop. Datadef exposes an MCP server with 36 tools: nine outcome-level ones, including create_diagram, edit_diagram, export_diagram, repo_status and repo_refresh, and 27 canvas_* tools for node-by-node edits. An assistant such as Claude Code or Cursor reads the Jenkinsfile and the shared library in the working tree and updates the existing canvas rather than drawing a new one. Running that as a post-merge step filtered to the Jenkinsfile path keeps the drift window to one merge. The handshake and the tool listing answer without a key, so a client can inspect the surface before anyone issues one. The setup is covered in the MCP diagram server guide.

The second is publication. Publish the diagram as a live embed and point the README, the Confluence page, and the onboarding doc at the same URL. When the canvas updates, all three follow, and nobody has to remember which pages held a copy of the old PNG.

• GitHub Actions workflow diagram
• Keep the pipeline diagram up to date
• The Datadef MCP diagram server
• MCP server documentation