CI/CD architecture diagram: the machinery underneath the stages

The common mistake is drawing one diagram and expecting it to answer both questions. Adding a runner box to a stage flow produces something that is neither: the stages lose their rhythm and the infrastructure is represented by a single shape that hides the interesting part, which is where that runner sits relative to your networks.

Keep the subjects apart. The pipeline diagram is about an artifact and time. The architecture diagram is about systems and trust boundaries, with no time axis at all. When a reader asks "why can the deploy job reach the database but the test job cannot", they are asking an architecture question and no amount of stage detail will answer it.

The two diagrams share vocabulary, and that is enough coupling. If a stage is called Publish on one, the registry it writes to should be called Registry on both.

The runner fleet, split by kind. Hosted runners and self-hosted runners have different network positions and different threat models, so they are different shapes. Label self-hosted pools with what identifies them in the config: the label set, the scaling mechanism, the subnet or cluster they run in.

The artifact registry, with the retention rule written on it, because retention is what determines whether the rollback arrow on your pipeline diagram actually works. A rollback to a two-week-old tag fails quietly when untagged images are pruned after seven days.

The credential path. This is the shape teams most often omit and reviewers most often ask about. Either the runner holds long-lived keys from a secret store, or it exchanges a short-lived OIDC token for cloud credentials at job time. Those are different arrows, different failure modes, and different audit answers.

The environment targets, drawn as the accounts, subscriptions, or projects they really are. Dev and production sharing one account is an architectural fact that belongs on a diagram, not in a footnote.

# One arrow on the architecture diagram, spelled out in the workflow
permissions:
  id-token: write   # runner asks the provider for a short-lived token
  contents: read

jobs:
  deploy:
    runs-on: [self-hosted, linux, arm64, prod-egress]  # names the runner pool
    environment: production
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111122223333:role/deploy   # the trust edge
          aws-region: eu-west-1

Three boundaries carry almost all the value. The boundary between the git host and your network, because that is where a compromised action or a forked pull request tries to cross. The boundary between the runner and each environment account, because that is what separation of duties means in practice. And the boundary around the secret store, because everything else on the diagram is a path towards it.

Draw them as zones and let the arrows cross them visibly. An arrow that crosses two boundaries in one hop is either a mistake in the diagram or a finding in the review, and either way you want to see it.

Annotate the crossings with what makes them legitimate: an OIDC subject claim restricted to a branch, a network rule allowing one CIDR, an approval gate that is enforced by the environment rather than by convention. Those annotations are what turn a picture into evidence during an audit.

Unlike a pipeline diagram, most of a CI/CD architecture diagram is already declared in infrastructure code: the runner autoscaling group, the registry and its lifecycle policy, the IAM roles and their trust policies, the network rules. That means it can be generated rather than transcribed.

Datadef connects to a GitHub, GitLab, or Azure DevOps repository with read-only access, on a branch or a tag, and regenerates the diagram and an architecture document on a daily sync. For Terraform repositories, every .tf file is parsed directly, with no terraform init, no state file, and no cloud credentials involved, and module directories become zones. The runner module, the registry module, and the per-environment accounts land as the zones you would have drawn by hand. A module pulled from a registry or a git source is not expanded, since its body is not in your repository; it becomes one node standing for everything it provisions, carrying the version the call pins. See repository sync for the connection details and Terraform diagrams without state for why the parse-only approach matters here.

One consequence is worth knowing before you rely on it here. The parser treats identity wiring as glue and counts it rather than drawing it: aws_iam_role, aws_iam_policy, aws_iam_role_policy_attachment, azurerm_role_assignment, google_project_iam_member, and anything whose type name matches role, permission, grant, member, or policy_attachment. That is the right default for an infrastructure diagram, where forty role assignments would bury the systems, and it is the wrong default for this one, whose whole subject is the trust boundaries. So the generated base gives you the runner pool, the registry, the accounts, and the network, and you draw the credential edges on top of it yourself.

The pieces that are not in code, the approval policies configured in the CI product UI, still need to be added by hand on the canvas. That is a small annotation job on top of a generated base, which is a very different maintenance burden from redrawing the whole thing each quarter.

• How to draw a CI/CD pipeline diagram
• Terraform diagrams without state or init
• Keep infrastructure docs in sync with Terraform
• Repository sync documentation
• Repo to diagram