CI/CD Pipeline Diagram: From Commit to Production, Step by Step

Ask for a CI/CD diagram and you usually get a row of boxes: build, test, deploy. It is not wrong, and it answers almost none of the questions people bring to it. What exactly gets deployed? Who can push to production? Where are the approvals? How do we roll back, and what tells us we need to?

This guide shows how to draw a CI/CD pipeline diagram that answers those questions, using a common setup as the example: GitHub-style pull requests, a container registry, and GitOps deployments to Kubernetes with Argo CD. The rules apply just as well to other tools.

What a pipeline diagram should show

• Triggers. What starts each part: a pull request, a merge to main, a tag, a schedule.
• Stages and their order. Lint, test, build, scan, deploy, verify.
• Artifacts. The thing that moves between stages, usually a container image. Show how it is identified: a tag, or better, a digest.
• Environments. Where the artifact runs, and in which order it gets there.
• Gates. Manual approvals, required checks and policies that stop a change.
• Credentials. Which system can change which environment.
• Feedback. How production signals stop or roll back a bad release.

A row of stages covers the first two. The rest is where incidents and audits happen.

The example: GitOps to Kubernetes

1. A developer opens a pull request in the app repository.
2. CI runs on every push: lint, unit tests, build the image, scan it. On a merge to main it pushes the image to the registry and records its digest.
3. CI then commits the new image digest to the staging overlay in a separate config repository.
4. Argo CD in the staging cluster notices the commit, pulls the config and syncs the cluster.
5. To promote, someone opens a pull request that copies the reference to the production overlay. A required review is the approval gate.
6. After the merge, Argo CD in production syncs, and Argo Rollouts, a separate controller in the cluster, releases the new version as a canary: a small share of traffic first, then all of it.
7. During the canary, Argo Rollouts runs an analysis against Prometheus metrics. A failed analysis aborts the rollout and shifts traffic back to the stable version, and alerts page the on-call engineer.

Two details on this diagram are easy to miss and matter a lot. CI never talks to a cluster: it only pushes the image to the registry and commits to Git. And production changes only through a reviewed commit, which is also how you roll back: revert the commit, and Argo CD syncs the previous version.

Push or pull: draw where the credentials live

In a push-based pipeline, CI holds credentials for the cluster and runs the deploy command itself. In a pull-based GitOps setup, an agent inside each cluster, such as Argo CD or Flux, pulls the desired state from Git and applies it, so nothing outside the cluster needs write access to it.

Both are valid, and the diagram should make the choice obvious. For push, draw an edge from CI to each cluster and label it with the credential it uses. For pull, draw the config repository feeding the agent in each cluster, and no edge from CI to any cluster. Reviewers can then see the blast radius of a leaked CI secret at a glance.

If CI needs cloud access, for example to push images, note how it gets it. Short-lived tokens through OpenID Connect are a better story on a diagram than a long-lived key stored as a secret.

Rules for a readable pipeline diagram

Make the artifact visible

Label the edge into the registry with the artifact and how it is identified: image shop-api, by digest. Tags can be moved; a digest always points to the same image. If you also produce an SBOM or a signature, show them next to the image.

Draw environments as frames

Each environment is a frame with its deploy agent and its cluster inside. The order of the frames shows the promotion path, and anything that skips a frame stands out.

Give gates their own node

An approval is a step with an owner, not a label on an arrow. Draw it as a node between environments and say who approves: approve: release manager or 2 reviews required.

Close the loop

A pipeline that ends at "deploy" has no feedback. Draw what watches production and what it can do: stop a canary, page a person, trigger a rollback.

Keep job details in the CI file

Twelve parallel test jobs belong in the CI configuration. On the diagram, one stage node with a short label (lint, test, build, scan) is enough.

Common mistakes

• No artifact. Boxes connected by arrows that carry nothing in particular. Readers cannot tell what is promoted.
• Environments as stages. "Deploy staging" and "deploy prod" as two boxes in a row hide that they are different places with different permissions.
• Missing rollback path. If nobody can point to it on the diagram, it probably has not been tested.
• Every job as a node. The diagram turns into the CI log.
• Tools instead of responsibilities. A box labeled with a product name says less than build and scan image.

Build it in Archboard

1. Sign in with Google or GitHub and create a diagram.
2. From the DevOps pack, add Repository nodes for the app and config repositories and a Pipeline for CI. Add a Docker pack Registry.
3. Add a Core Frame for each environment, with a DevOps pack Deploy node for Argo CD (and Argo Rollouts in production) and a Cloud pack Kubernetes Cluster inside.
4. Add a Diamond shape from the Core pack for the approval gate.
5. Add DevOps pack Metrics and Alert nodes and C4 Model Person nodes for the developer and the on-call engineer.
6. Connect ports, label every edge with what flows, and make the feedback edge dashed.

The example uses 15 diagram nodes, the Free plan's limit. For a pipeline with observability built in, open /examples/cicd-observability; for the cluster side, see how to draw a Kubernetes architecture diagram.

FAQ

Should I draw every CI job? No. Group jobs into stages and keep the details in the CI file. Draw a job separately only when it is a gate, such as a security scan that blocks the release.

How do I show feature flags? As a separate system next to production, with an edge to the services that read flags. Flags change behavior without a deploy, so they deserve their own line on the diagram.

Where do secrets go on the diagram? Show which system holds which credential and for what, not the secrets themselves. For CI, note whether it uses short-lived OIDC tokens or stored keys.

Do I need one diagram per repository? Usually one diagram per delivery path. If many services share the same pipeline, draw it once and list the services in a note.

How do I keep the diagram current? Review it when the pipeline changes, the same way you review the CI file. Link the live diagram from the repository's README so there is only one copy.

Start free — one seat, no credit card.