How to draw a CI/CD pipeline diagram: one artifact, five stages, under twenty five nodes

Two questions settle most of the layout. What single thing moves through this pipeline, and what makes it start. The artifact is usually a container image, a versioned package, or a bundle. Naming it forces the diagram to be about promotion rather than about tasks, and promotion is what readers ask about: what is running in production, and how did it get there.

The trigger belongs on the left edge with the event named, not the vendor. Push to main, tag matching v*, pull request opened, schedule at 02:00 UTC, manual dispatch. A diagram that opens with a tool logo tells you who sells the runner. A diagram that opens with "push to main" tells you when the thing happens, which is the question people actually arrive with.

If your answer to the first question is "three different things", you have three diagrams. A monorepo that builds an API image, a web bundle, and a Terraform plan should not draw all three in one frame. The shared prefix (checkout, install, lint) is the only part they have in common, and it is the least interesting part of any of them.

Source, build, test, publish, deploy. Almost every pipeline in production is a variation on those five. Left to right beats top to bottom because promotion already reads as rightward movement in every other diagram your team owns, and because gates sit naturally between columns.

Make the artifact a shape, not a label on an arrow. A build stage that produces ghcr.io/acme/api:sha-9f2c1a deserves its own node, because the registry is the join between the CI half and the CD half of the picture. When an incident asks which image is in production, the diagram needs a place to point at.

Test is one stage, not five. Unit, contract, integration, and end to end runs belong inside one node with the list underneath, unless they run in different environments or gate different things. The exception earns its own box: a security scan that can block the publish is a gate, so draw it as a gate rather than as another test.

# .github/workflows/release.yml, trimmed to what the diagram shows
on:
  push:
    branches: [main]

jobs:
  build:            # node: Build image
    outputs:
      image: ghcr.io/acme/api:${{ github.sha }}
  test:             # node: Test suite (unit, contract, integration)
    needs: build
  publish:          # node: Registry, the artifact object itself
    needs: test
  deploy-staging:   # node inside the Staging zone
    needs: publish
    environment: staging
  deploy-prod:      # node inside the Production zone, behind a gate
    needs: deploy-staging
    environment: production   # the approval lives here: draw it as a gate

A flow diagram answers "what happens next". Stages as boxes, arrows for progression, gates as decision shapes. It is the right form for onboarding, for the header of a runbook, and for any reader who does not know which system owns which step, because it maps to time rather than to ownership.

A sequence diagram answers "who calls whom". Lifelines for the git host, the CI runner, the artifact registry, the secret store, and the target cluster, with messages between them. Reach for it when the interesting failure is a handoff: an OIDC token exchange that expires mid-deploy, a self-hosted runner that cannot reach a private registry, a webhook that fires twice. A flow diagram will never reveal that credentials are fetched at deploy time rather than at build time.

Most teams need the flow diagram on the wiki and the sequence diagram in the security review. Drawing both is cheaper than arguing about which single diagram serves both audiences, and the two only need to agree on stage names.

A pipeline diagram stops working somewhere around thirty shapes, which is roughly where readers start scanning instead of reading. Twelve to twenty five nodes covers a real pipeline including environments and gates. Past that, split rather than shrink the font.

That number is not only taste. Datadef enforces the same budget in code when it draws infrastructure from a repository: a module zone holds at most eight nodes before its remainder collapses into one counted node, and the whole canvas targets forty. Run against a real Azure platform of 123 declared resources and 30 data lookups spread over five stacks, the curation produced 36 nodes in 12 zones, with the largest zone holding nine. A delivery pipeline is a smaller subject than a cloud platform, so a pipeline diagram that needs more than thirty shapes is almost always two diagrams.

Three splits work. By artifact, one diagram per deployable. By half, a CI diagram that ends at the registry and a CD diagram that starts there, with the same artifact node drawn in both so the seam is obvious. By altitude, one overview for the wiki and one detailed view per stage for the team that owns that stage.

Collapse repetition instead of drawing it. A matrix that builds three architectures is one node reading "build, matrix: amd64, arm64, armv7". GitHub caps a single matrix at 256 jobs per workflow run, which is the upper bound on how many identical boxes a faithful drawing could contain, and the only part of those 256 that carries information is the number. Twelve services deployed by the same reusable workflow is one node with the count, not twelve identical lanes. In the Datadef editor those become a zone with a count, and the full list stays in the accompanying doc rather than on the canvas.

• What belongs in a CI/CD pipeline diagram
• Workflow diagram vs pipeline diagram
• Environments and approval gates
• Keep the pipeline diagram up to date
• Diagram templates