CI/CD Diagram Guide

Showing environments and approval gates in a CI/CD diagram

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Environments are zones, not stages. That one decision fixes most of what goes wrong in deployment pipeline diagrams, because it forces the picture to show a single artifact being promoted into successive places rather than a chain of tasks that happen to have environment names. Once the zones exist, the gates between them have somewhere to sit, and each gate can carry the three attributes that make it meaningful.

Try it free
6 min readFor teams documenting promotion from dev through staging to production

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

223/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Environments are zones, stages are steps

A stage is something that happens. An environment is somewhere that exists whether or not a pipeline is running right now. Drawing production as a box in a left-to-right chain of stages quietly claims that production only exists at the end of a pipeline run, which is exactly backwards during an incident.

Zones also solve the many-to-many problem. Several pipelines deploy to staging, one pipeline deploys to several environments, and some environments are reached only by a tag or a manual dispatch. Boxes in a chain cannot express any of that. Zones with arrows entering them can.

The practical layout that works: stages across the top as a row, environment zones below, and promotion arrows from the publish stage down into each zone. The reader sees the pipeline once and the environments once, instead of the pipeline repeated per environment.

One artifact, promoted, never rebuilt

Draw the artifact entering each zone as the same node identity. If the image ghcr.io/acme/api:sha-9f2c1a is deployed to staging and then to production, the arrow into production should start from the artifact, not from the staging deployment. That distinction is what makes it visible when a pipeline rebuilds per environment, which is a common and quietly dangerous pattern: the thing that was tested is no longer the thing that ships.

Configuration is the legitimate difference between environments, so draw where it comes from. A config source node feeding each zone, whether that is a parameter store, a variable group, or a values file per environment, answers the question that otherwise generates a support thread every onboarding cycle.

When environments live in separate cloud accounts, subscriptions, or projects, put that on the zone label. Account boundaries are the strongest form of isolation most teams have, and a diagram that shows dev and production sharing one account has communicated something important without saying a word.

A gate has three attributes, and a label with one of them is not enough

Who. The approving group, named. "Release managers" or "platform on-call", not "manual approval". If self-approval is blocked, that is part of the who and belongs on the label, since it is the first thing any separation-of-duties review asks about.

What runs automatically. Many gates are not purely human: a query against open incidents, a check for active monitoring alerts, a policy scan, a business-hours window. These run before or alongside the approval and can block promotion on their own, so they earn a small shape feeding the gate.

What the timeout does. A gate that auto-rejects after 48 hours and a gate that waits forever produce very different behaviour on a Friday evening, and the difference is invisible unless it is written down. Check the real default before writing it: an Azure Pipelines approval times out after 30 days, can be extended to 365, and marks the stage skipped rather than failed when it does. Add the direction of the timeout, not just the duration.

Weak label      [ Manual approval ]

Useful label    [ Approval: release-managers
                  auto-checks: no open Sev1, business hours
                  timeout: 48h -> auto-reject
                  self-approval: blocked ]

The rollback path belongs to the gate story

Every gate implies a decision that can go wrong, so every diagram with gates needs an exit. Draw a reverse edge from the production zone to the previous artifact version, labelled with the mechanism: redeploy previous tag, revert and rerun the pipeline, or shift traffic back to the stable revision. Those three have different recovery times and the label is where that gets recorded.

Check the rollback against reality while drawing it. If the arrow says "redeploy previous tag" and the registry prunes untagged images after seven days, the arrow is aspirational. Diagrams are unusually good at surfacing this kind of mismatch because they force two facts that live in different systems onto the same page.

Finally, draw the break-glass path if one exists, as a dashed edge with its condition. An emergency route that bypasses the gate is not made safer by being left off the diagram, and teams that draw it tend to be the ones who eventually remove it.

Zones make counts possible

Once environments are zones, repeated resources inside them carry counts instead of being drawn one by one. Datadef does this deterministically when it draws from a repository: two or more resources of the same type inside one module become a single node labelled with the count and described with the member names, as in "Storage credentials ×2: external, root", and a zone still over eight nodes folds its remainder into one "Supporting resources ×N". That is how a twelve-service promotion diagram stays under twenty five shapes.

FAQ

How do I show environments in a CI/CD pipeline diagram?

Draw them as zones rather than as stages in the flow, and send promotion arrows from the publish stage into each zone. Environments exist independently of a pipeline run, several pipelines can target the same one, and one pipeline can target several, none of which a linear chain of boxes can express.

What should an approval gate label say?

Three things: who approves, what automated checks run alongside the approval, and what the timeout does. For example, approval by release managers, blocked while a Sev1 incident is open, auto-rejecting after 48 hours, with self-approval disabled. A gate labelled only "manual approval" answers none of the questions people bring to the diagram.

Should the same artifact be shown in every environment?

Yes, and using the same node identity. Promotion means the artifact tested in staging is the one that reaches production. Drawing the arrow into production as starting from the artifact rather than from the staging deployment also makes it obvious when a pipeline rebuilds per environment, which breaks the guarantee that staging tested what ships.

How do I show environment-specific configuration?

As a configuration source node feeding each environment zone, named for what it really is: a parameter store path, a variable group, or a values file per environment. Configuration is the legitimate difference between environments, so it should be visible rather than implied.

Should the diagram include the emergency deployment path?

Yes, drawn as a dashed edge with the condition that allows it. A break-glass route that bypasses the approval gate exists whether or not it is on the diagram, and leaving it off only removes it from review. Teams that draw it are usually the ones who eventually manage to remove it.