The short answer: a useful CI/CD pipeline diagram shows the release contract, not just a row of tools. Draw the trigger and source revision, the dependency order of build and verification jobs, the one identifiable artifact that crosses into delivery, every environment gate, and the observation or rollback path. If a reviewer cannot point to what gets promoted and what stops a bad release, the drawing is incomplete.
CI and CD answer different questions. Continuous integration turns a source revision into tested evidence and a releasable artifact. Continuous delivery or deployment moves an approved artifact through environments. Keep those phases visually separate, then connect them through an artifact identity such as a package version or image digest.
Scope: this is a documentation and review method, not a universal CI/CD notation or a claim that every team needs the same stages. The worked example is illustrative. GitHub product behavior and the SLSA specification were last checked August 28, 2026; verify current platform settings before implementation.
Which CI/CD diagram do you actually need?
Start with the review question. A single giant “DevOps architecture” picture usually mixes four useful diagrams and makes none of them reliable.
| Reader's question | Best view | Required evidence |
|---|---|---|
| Which job runs after which? | Job dependency graph | Triggers, conditions, parallel jobs, failure and skip behavior |
| What exactly reaches production? | Artifact lineage view | Source revision, build run, artifact identity, digest, attestation or SBOM when used |
| Who or what can release? | Environment promotion map | Environments, approvals, branch or tag rules, secret and runner boundaries |
| How do we recover? | Deployment state and rollback view | Health signals, decision owner, previous known-good artifact, rollback or roll-forward path |
| Which system owns each control? | Trust-boundary view | Source host, build platform, registry, deploy controller, identities, external actions |
Use one release-contract sheet when the pipeline is small enough to read without crossing arrows. Split it when job-level detail hides the promotion path, or when a security review needs identities and trust boundaries that would overwhelm an operator's release view.
The five parts every release-contract diagram needs
1. Source revision and trigger
Name the event that starts the pipeline and the revision it binds to: pull request, merge to a protected branch, signed tag, scheduled run, or approved manual dispatch. “GitHub” or “repo” is not a trigger. Record any path filters or conditions that can prevent a run, because those branches explain why apparently identical changes take different routes.
2. Job dependencies and stop conditions
Draw dependencies, not the incidental order in a YAML file. GitHub's current workflow documentation says jobs.<job_id>.needs makes a downstream job wait for successful prerequisite jobs; a failed or skipped prerequisite propagates through that dependency chain unless a condition changes the behavior. The diagram should therefore distinguish parallel tests from true gates and label exceptions such as a cleanup job that runs after failure.
3. The artifact and its evidence
Put the build output in a first-class box. Give it an identity that survives the drawing: package version, object key, release ID, or container digest. Connect the artifact to the source revision and build run that produced it.
NIST SP 800-204D describes a CI/CD pipeline carrying source through build, test, package, and deployment while integrating software supply-chain security measures. SLSA 1.2 makes provenance progressively stronger across its Build levels: L1 requires provenance showing how a package was built, L2 adds signed provenance generated by a hosted build platform, and L3 adds a hardened build platform. Your diagram does not prove a SLSA level, but it should show where provenance is produced and where verification happens if the system depends on it.
4. Environment gates and authority
Label each environment and the rule that permits entry. A generic diamond marked “approval” hides the important fact: approval may come from a person, a test result, a policy service, or a protected branch rule. It also hides which identity gets access to deployment secrets.
GitHub's deployment-environment documentation currently allows required approval, branch restrictions, custom protection rules, and delayed access to environment secrets until protection rules pass. Other platforms use different primitives. Draw the control you actually configured, not the control your team assumes exists.
5. Observation and recovery
Production is not the end node. Show the health signal, observation window, decision owner, and response path. A rollback arrow should point from a failed deployment decision to a previous known-good artifact or release. If the real procedure rebuilds old source, show that honestly and flag the extra uncertainty; do not draw a clean “promote same artifact” story that the system does not implement.
Worked example: build once, promote by digest
The figure uses a small web service. A merge to main binds the run to commit 9f2a1c7. Unit and integration tests can run in parallel after dependency installation; the image build waits for both. The build produces web@sha256:7bd… plus test reports, an SBOM, and provenance. Those outputs are records, not decorative side notes.
The CD phase deploys that same digest to staging. Smoke tests and policy checks must pass before the production environment can receive it. A required reviewer then approves the release. Production health is observed against defined signals; failure sends the deploy controller to the prior approved digest. No box silently recompiles the application between staging and production.
This design is not automatically correct for every system. Mobile applications, firmware, database migrations, infrastructure changes, and multi-region releases may require separate artifacts, irreversible steps, compatibility rules, or staged rollout states. Add those constraints instead of squeezing them into a generic “deploy” box.
What the diagram must not imply
A scan box guarantees safety. A scanner only establishes that a specific check ran against a specific input under a specific policy. Label what happens on timeout, tool failure, or an accepted exception.
The pipeline platform is one trust zone. NSA and CISA's CI/CD guidance treats development and delivery environments as attack targets and recommends strong authentication, least privilege, secured secrets, hardened build systems, auditing, and monitoring. Show external actions, self-hosted runners, registries, deploy identities, and secret boundaries when they change who can affect a release.
Artifact storage is the same as dependency caching. GitHub distinguishes workflow artifacts—files persisted or shared after jobs—from caches used to speed repeated work. If a later job deploys an output, call it an artifact and record its identity.
The diagram is executable truth. Keep pipeline configuration as the execution source of truth. The drawing explains contracts, ownership, and exceptions that code alone does not make obvious. Put an owner, source file, last verified date, and change trigger on the sheet so it can be reviewed with the code.
Why these formats were prioritized on ChatDiagram
In the 30 full Pacific Time days from July 29, 2026 00:00 through August 28, 2026 00:00, 7,778 artifact-producing users saved 23,553 diagram artifacts on ChatDiagram. Flowcharts reached 1,401 users and 4,491 artifacts; block diagrams reached 563 users and 736 artifacts. One user may appear in both categories, so the percentages are not additive.
The query selected only artifact timestamp, opaque user and chat identifiers, engine, and type. It excluded [email protected] inside the database predicate and returned no email, prompt, title, diagram content, or artifact payload. Engine metadata can show demand for flowchart and block-diagram formats; it cannot identify which artifacts described CI/CD. The current guide was selected from aggregate format demand plus Google Search Console query demand, not by reading customer work.
The 15-minute review checklist
- The title states the system, scope, owner, and last verified date.
- Every entry trigger and condition is named.
- The source revision is traceable to the build run.
- Parallel work and true dependency gates are visually different.
- Failure, skip, timeout, and exception behavior are not silently merged.
- The releasable artifact has a stable ID, version, or digest.
- Test reports, SBOM, provenance, and attestations appear only where they really exist.
- Artifact production and artifact verification are separate actions.
- Environments state their entry rule and approving authority.
- External actions, runners, registries, secrets, and deploy identities cross visible trust boundaries.
- Staging and production receive the same artifact when “build once” is the policy.
- Production has named health signals and an observation window.
- Rollback names a known-good artifact and the actor or automation allowed to deploy it.
- Irreversible steps such as migrations are marked with their compatibility or recovery rule.
- The diagram links to its pipeline definition and changes in the same review when the contract changes.
Use the checklist against the current pipeline before redrawing it. When the facts are verified, start from ChatDiagram's CI/CD pipeline process template, replace every generic box with the real trigger, artifact, gate, owner, and recovery rule, then review the result beside the executable configuration.