# CI/CD pipeline diagram

Pipeline diagrams are worth drawing because the gates are where arguments happen: what runs automatically, what needs approval, and what can be skipped in an emergency.

Draw the emergency path. Every pipeline has one, and undocumented ones get used badly.

---

## When to reach for one

* Documenting a release process for a team or an auditor.
* Designing a pipeline before building it.
* Explaining why a deploy takes forty minutes.

---

## How to draw it in Capable

| **Route** | **Use when**                                                   |
| --------- | -------------------------------------------------------------- |
| Mermaid   | Stages and gates, kept next to the pipeline definition.        |
| Graphviz  | Generated from a pipeline definition where the tooling allows. |

---

## A worked example

A pipeline with a manual gate and a hotfix path:

![CI/CD pipeline diagram](https://help.gocapable.com/images/att1417904172.svg)

The source, which you can paste into a new diagram and edit:

```
flowchart LR
  C([Commit]) --> B[Build]
  B --> U[Unit tests]
  U --> I[Integration tests]
  I --> S[Deploy to staging]
  S --> E[End to end tests]
  E --> G{Manual approval}
  G -- Approved --> P[Deploy to production]
  G -- Rejected --> X([Stop])
  P --> M[Smoke tests]
  M -- Fail --> R[Automatic rollback]
  H([Hotfix branch]) -.-> B
```

---

## A few things that catch people out

* Show what is automatic and what needs a human. That distinction is the whole diagram.
* Include rollback. A pipeline diagram that ends at deploy is only half the process.
* Stage timings are worth annotating if anyone has ever complained about the wait.

---

## Related

[Cloud architecture diagramProvider icons, or text that lays itself out.](https://help.gocapable.com/diagrams/cloud-architecture-diagram.html)

[AWS architecture diagramVPCs, subnets and the icons everyone knows.](https://help.gocapable.com/diagrams/aws-architecture-diagram.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Draw the trust boundary._