CI/CD pipeline
From commit to production with tests and review gates.
Every engineering team has a deployment pipeline; far fewer have a picture of it that survives contact with reality. This template draws the whole journey — commit, CI tests, code review, staging, smoke tests, production, monitoring — including the unglamorous return paths: failed tests notify the author, a rejected review sends the change back to a new commit, and a failed smoke test stops the release before customers see it.
The left-to-right layout reads like a timeline, which makes it a natural fit for onboarding docs and architecture wikis where people scan horizontally.
When to use this template
- Onboarding new engineers — show how a change actually ships before they open the CI config. The gates and feedback loops are clearer in twelve nodes than in three hundred lines of YAML.
- Pipeline design reviews — when you are adding a gate (security scan, canary stage), sketch it here first so the team can argue about the flow before anyone writes automation.
- Audit and compliance documentation — auditors ask "how does code reach production?" constantly. This diagram answers it in one screen, with the review and approval gates explicit.
How to adapt it
Rename the stages to match your real pipeline, then extend the gates you actually enforce:
- Add a security or dependency scan node between CI tests and code review.
- Insert a canary deployment step between staging and production, with its own metrics check looping back to rollback.
- Split "Run CI tests" into lint, unit, and integration stages if failures at different layers route to different people.
Drag nodes and redraw arrows in the visual editor — every visual edit regenerates clean Mermaid code, so the diagram you refine on screen is the same text you commit next to your pipeline definition.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart LR
A[Push commit] --> B[Run CI tests]
B --> C{Tests pass?}
C -->|No| D[Notify author]
D --> A
C -->|Yes| E[Code review]
E --> F{Approved?}
F -->|No| A
F -->|Yes| G[Deploy to staging]
G --> H{Smoke tests OK?}
H -->|No| D
H -->|Yes| I[Deploy to production]
I --> J[Monitor + rollback if needed]
Frequently asked questions
- What is a CI/CD pipeline diagram?
- It is a visual map of how code moves from a developer's commit to production: automated tests, code review, staging deployment, smoke tests, and the production release with monitoring. Each diamond is a quality gate, and the arrows back to the start show exactly what happens when a gate fails — something prose runbooks often leave ambiguous.
- How do I render Mermaid in GitHub?
- Paste the code into any Markdown file, issue, or pull request inside a fenced code block labelled mermaid (three backticks followed by the word mermaid). GitHub renders it automatically — no plugins or images needed. That makes this template ideal for a CONTRIBUTING.md or README, since the pipeline diagram lives next to the code it describes and updates via normal pull requests.
- Why use left-to-right (LR) orientation for pipeline diagrams?
- Pipelines are naturally linear — commit on the left, production on the right — so flowchart LR reads like a timeline and fits nicely in wide documentation pages. Top-down (TD) suits decision-heavy flows with many branches. Switching is a one-word edit: change LR to TD on the first line and Mermaid re-lays out the whole diagram.
- Should the diagram match my actual CI configuration?
- Yes — treat it as documentation of intent, reviewed whenever the pipeline changes. The diagram captures the logical gates (tests, review, staging, smoke tests) rather than vendor-specific YAML, so it stays valid whether you run GitHub Actions, GitLab CI, or Jenkins. Many teams link each node to the corresponding job definition for quick navigation.