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 difference in one sentence, then the consequences
The workflow diagram is a picture of an execution. The pipeline diagram is a picture of a policy. That single difference explains everything else: the workflow graph has a status colour per node and an end time, while the pipeline diagram has environments, approvers, and a rollback path that no single run contains.
It also explains why screenshots of the run graph age badly on a wiki. The screenshot is dated the moment it is taken, it shows the state of one commit, and it silently omits every job that did not run because its condition was false that day. A reader cannot tell from the picture whether the missing deploy job does not exist or simply did not fire.
The two views also disagree about parallelism. A run graph shows what actually ran concurrently on that occasion, which depends on runner availability. A pipeline diagram states what is allowed to run concurrently, which is a design decision worth writing down.
Where the workflow graph already exists, for free
GitHub Actions draws a visualization graph on every run page, with one node per job and edges derived from needs. GitLab renders a pipeline graph with stages as columns and, in DAG view, the edges declared by needs cutting across stage boundaries, bounded by the ci_needs_size_limit plan limit that defaults to 50 dependencies per job. Jenkins has Stage View and the Pipeline Graph View plugin, which is where this view is heading now that Blue Ocean has stopped taking new features. Azure Pipelines shows stages and their dependencies on the run summary.
All four share the same two limits. They show one workflow or one pipeline definition at a time, so a repository with six workflow files has six graphs and no combined picture. And they live in run history, so the view expires with the retention policy. On GitHub that default is 90 days for logs and artifacts, configurable between 1 and 90 days on public repositories and between 1 and 400 days on private and internal ones. A wiki link to a run graph is a link with an expiry date, and the expiry is measured in months.
That makes them excellent for debugging a specific failure and unsuitable as documentation. Use them for the question they answer, and stop trying to make them the architecture page.
Fact run graph (free) standing map (drawn) ----- ---------------- -------------------- job and stage names yes yes status and duration yes no jobs that did NOT run no yes environments no yes approver on the gate no yes artifact identity sometimes yes rollback path no yes reusable workflow callers no yes lifetime 90 days by default as long as the URL
What the standing map has to contain that no run has
Environments as first-class zones, including the ones only reached on tags. Gates with the approving group named. The artifact identity and where it is stored between the CI half and the CD half. The rollback path. Cross-workflow relationships: the reusable workflow four repositories call, the child pipeline triggered by the docs job, the release workflow that only fires from a tag.
Those facts come from reading the whole configuration, not from watching one execution. For GitHub Actions the source is the needs graph across every file in .github/workflows plus the workflow_call entry points, covered in detail in the GitHub Actions needs graph. For GitLab the source is the merged YAML after include resolution, covered in resolving GitLab CI includes.
Once drawn, the standing map is the one that belongs on the wiki, in the onboarding doc, and in the README. Publish it as a live embed so those three places show the same canvas rather than three screenshots taken on three different days.
A standing map only stays worth publishing if it holds still between updates. Datadef hashes what actually feeds a diagram, the parsed plan for a Terraform repository and the assembled corpus otherwise, and a sync whose hash has not moved skips generation altogether: no tokens, no redraw, no new arrangement for readers to relearn. A commit that touches a README, a test, or a comment moves the commit sha and leaves that hash alone, which covers most commits in most repositories.
When to draw a sequence instead of either
There is a third shape people reach for and then mislabel. A sequence diagram is neither a run graph nor a standing map: it shows the conversation between systems during a deploy. Git host notifies CI, CI requests an OIDC token, cloud provider returns short-lived credentials, runner pushes to the registry, deploy controller pulls the image, health check reports back.
That view is worth drawing exactly once per delivery architecture, and it is the view that catches the failures the other two cannot express: token lifetimes shorter than a slow deploy, a registry pull happening from a network segment that cannot reach it, a webhook retried twice producing two deployments.
A practical rule: the run graph is per failure, the standing map is per team, and the sequence diagram is per architecture change. Their update rhythms differ by an order of magnitude, which is a strong hint that they should never be the same file.
FAQ
What is the difference between a CI/CD workflow diagram and a pipeline diagram?
Can I use the GitHub Actions visualization graph as documentation?
Does a pipeline diagram need to show parallel jobs?
How often does each kind of diagram need updating?
Which diagram belongs in the README?