See it as a diagram
Everything below, as a diagram you can edit. Describe yours and see it in seconds.
No account needed · Editable canvas, not a picture
The audience decides the contents, and there are three of them
A new engineer in week one wants to know where code goes after they merge, which environments exist, and who can push to production. They need stage names, environment names, and gates. They do not need to know that the integration suite runs on a self-hosted runner labelled arm64-large.
The on-call engineer at 3am wants two facts: what is deployed right now, and how to get the previous version back. That reader needs the artifact identity (image name and tag scheme), the deploy target, and a rollback path drawn as a real arrow rather than mentioned in a caption.
The auditor or the security reviewer wants evidence of separation of duties: who approves production, whether the approver can approve their own change, where secrets come from, and whether any path skips the gate. That reader needs the gate annotated with an approver group and needs emergency paths drawn rather than hidden.
One diagram can serve all three if it stops at that level. It cannot serve all three plus the pipeline author who wants step-level detail, which is why the step-level view stays in the config file.
The include list
The trigger event, named as an event: push to main, tag v*, pull request opened, schedule. The artifact, with its real coordinate scheme, because "image" is not an answer during an incident and ghcr.io/acme/api:sha-9f2c1a is. The stages, five or so, each one a phase rather than a command.
The environments, drawn as zones rather than as stages, so it is visible that the same artifact enters each of them. The gates, each with the approving group written on it. The rollback path, drawn from production back to the previous artifact. The owner of the pipeline, as a caption, because every diagram that survives has a name attached to it.
One more item earns its place in regulated environments: the source of credentials. An arrow from the runner to a secret store or an identity provider is one shape and answers the single most common question in a pipeline security review.
Include Exclude ------- ------- trigger event the yaml step list artifact name and tag scheme linter and formatter names 5 stages per-step durations environments as zones every matrix leg gates with approver group retry and timeout settings rollback path runner sizes and labels secret or identity source branch protection rules pipeline owner tool logos used as content
The exclude list, with the reason for each
Step-level commands: they live in the workflow file, they change weekly, and a diagram that repeats them is wrong within a sprint. If someone needs the commands, they need the file, not a picture of the file.
Run durations: they are a property of a run, not of the pipeline. Putting "build: 4m12s" on a standing diagram freezes one sample of a distribution and invites arguments about a number nobody is maintaining.
Every matrix leg and every parallel shard: identical by construction, so drawing them multiplies shapes and adds nothing. One node with the matrix dimensions written on it carries the same information in one twelfth of the space.
The same include and exclude judgment exists as code inside Datadef, which is a useful sanity check on the list above. Its Terraform catalog tags 196 resource types as major, minor, or glue, 46 of them glue, and glue never becomes a box: role assignments, grants, IAM members and policy attachments, and every resource belonging to the random, null, local, time, tls, archive and template providers. They are counted in a note instead, which reads as "31 wiring resources not worth boxes: 14 role assignments, 9 grants, 8 key vault secrets". A CI/CD diagram has the same three tiers, and the same rule holds: the wiring gets a count, not a shape.
Tool logos as content: an icon next to a stage name is useful shorthand, and the editor carries 438 AWS icons, 624 Azure, 226 GCP and over two thousand in total for exactly that. A stage whose only label is a logo is not shorthand. The reader has to know what Argo does before they can read your diagram, which defeats the point of drawing one.
Three things almost every pipeline diagram is missing
The rollback path. Most diagrams end at a production box, which implies the pipeline is a one-way street. It is not, and the reverse arrow is the shape the on-call reader looks for first. Draw it, and label it with the mechanism: redeploy previous tag, revert commit and rerun, or traffic shift back to the stable revision.
The gate owner. "Manual approval" as a label answers nothing. "Approval, platform on-call, 24h timeout to auto-reject" answers three questions at once and makes the diagram useful in an audit without a second document.
The emergency path. Nearly every organisation has a break-glass route: a direct deploy, a hotfix branch that skips staging, an admin who can force a merge. Leaving it off the diagram does not remove it from reality, it just removes it from review. Draw it as a dashed edge with the condition on it.
One diagram, several audiences
FAQ
Should tool names appear on a CI/CD diagram?
Should I show test types separately on the diagram?
Do I need to draw the rollback path?
Should the diagram show the emergency or break-glass deploy path?
How detailed should a CI/CD diagram be?