# CI/CD Pipeline Diagrams in Confluence with Mermaid (Copy-Paste)

September 24, 2026 ·

<!-- -->

6 min read

[NGPilot](https://ngpilot.com)

A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a **documentation** problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier.

**Quick answer:** put the pipeline's shape in Confluence as a Mermaid `flowchart`, rendered by [Mermaid Plus for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence/). Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped.

## Why the pipeline's shape belongs in the wiki[​](#why-the-pipelines-shape-belongs-in-the-wiki "Direct link to Why the pipeline's shape belongs in the wiki")

A diagram of your CI/CD pipeline is the answer to the three questions every teammate asks with a red build on screen:

* **Where are we?** Which stage failed, and what came before it
* **What gets rerun?** Do fixes restart the whole pipeline or just the failed stage
* **Where does it stop?** What has to pass for a deploy to actually go out

Text in a README answers these slowly. A diagram answers them at a glance — and because it is Mermaid text, it answers them *accurately*. When someone edits the pipeline, editing one arrow in the Confluence page keeps the doc honest.

## Copy-paste 1: the linear stage view[​](#copy-paste-1-the-linear-stage-view "Direct link to Copy-paste 1: the linear stage view")

Start with the version that matches your pipeline dashboard: stages in a row, biggest gate near the end. This is the diagram to lead with in the space overview — everyone recognizes their own pipeline in it.

```
flowchart LR

  %% title: CI/CD pipeline — linear stage view

  A[Commit] --> B[Build]

  B --> C[Unit tests]

  C --> D[Integration tests]

  D --> E[Security scan]

  E --> F[Deploy to staging]

  F --> G{Approve release?}

  G -->|yes| H[Deploy to prod]

  G -->|no| I[Reject]
```

![CI/CD pipeline — linear stage view](/assets/images/ci-cd-pipeline-linear-stage-view-cdbd595aae1c1890b45f78cbae079474.svg)

Read left to right as one deploy cycle. The single decision at the end (`Approve release?`) is the human gate between staging and production — the box where a person, not a runner, picks what ships.

## Copy-paste 2: gates, retries and rollbacks[​](#copy-paste-2-gates-retries-and-rollbacks "Direct link to Copy-paste 2: gates, retries and rollbacks")

Real pipelines branch. Flaky tests retry, security scans kill the build, and a bad prod deploy rolls back to the last good tag. Draw those forks and the diagram becomes the troubleshooting map the on-call reads:

```
flowchart TD

  %% title: CI/CD with quality gates and rollback

  A[Push to main] --> B[Build image]

  B --> C[Unit + integration tests]

  C -->|pass| D[Security scan]

  C -->|fail| C2[Attempt one retry]

  C2 --> C

  C2 -->|retry exhausted| F3[Block merge]

  D -->|vulnerabilities| F3

  D -->|clean| E[Deploy to staging]

  E --> F{Smoke tests ok?}

  F -->|yes| G[Deploy to prod]

  F -->|no| H[Roll back to last release tag]

  G --> I[Tag release]
```

![CI/CD with quality gates and rollback](/assets/images/ci-cd-with-quality-gates-and-rollback-c2a6f42ad0b88e79b0372abf49dd3e38.svg)

Two decisions carry the whole story: the retry loop between tests and the scan (`C --> C2 --> C`), and the smoke-test fork after staging. The `Block merge` node is where a compliant pipeline *stops* — putting it in the diagram tells the reader the failure behavior as clearly as the success path.

## Copy-paste 3: deploy-to-tag as a gitGraph[​](#copy-paste-3-deploy-to-tag-as-a-gitgraph "Direct link to Copy-paste 3: deploy-to-tag as a gitGraph")

The flowchart shows the pipeline *logic*. The gitGraph below shows the *history* — which commit became a release tag, and which hotfix rode straight to prod. Keep both: the flowchart in the docs page, the gitGraph beside the release notes.

```
gitGraph

  title Deploy-to-tag: v1.3 hotfix ridealong

  commit id: "v1.2"

  branch release/1.3

  checkout release/1.3

  branch hotfix/payment

  checkout hotfix/payment

  commit id: "fix: timeout"

  checkout release/1.3

  merge hotfix/payment

  checkout main

  commit id: "feat: dashboard"

  checkout release/1.3

  commit id: "release: v1.3"

  checkout main

  merge release/1.3
```

![Deploy-to-tag: v1.3 hotfix ridealong](/assets/images/deploy-to-tag-v1-3-hotfix-ridealong-01ff4af7309bc4488c78d81559882299.svg)

This is the diagram to attach to a release page. When the postmortem asks "did the hotfix ride along cleanly?", one glance at the gitGraph answers it — the release line, the hotfix merge, the tag.

## Live vs. diagram: the tie to your actual pipeline[​](#live-vs-diagram-the-tie-to-your-actual-pipeline "Direct link to Live vs. diagram: the tie to your actual pipeline")

Mermaid's value here is not "prettier docs" — it is that the diagram is *maintainable text*. In [Mermaid Plus for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence/) the macro is a code editor with a live preview: edit a stage name, add a gate, and the rendered SVG updates as you type. When your pipeline adds a stage (they always do), the wiki's diagram changes in the same edit that changes the pipeline — no screen-share screenshot to retake.

Teams that keep a Mermaid pipeline diagram current report the same reflex as keeping a diagram next to a sprint board: someone spots the doc drift exactly one pipeline change after it happens, because the diagram is the shortest path from "we changed it" to "write it down".

## Where this lives beside your other DevOps diagrams[​](#where-this-lives-beside-your-other-devops-diagrams "Direct link to Where this lives beside your other DevOps diagrams")

This is the pipeline half of the DevOps pair; the other half is the branch topology. Keep the **pipeline logic** as a flowchart on the space page (this post), the **branch/release history** as a gitGraph on the relevant issue or release page ([branches & releases in Jira](/blog/mermaid-gitgraph-jira-branch-history.md)), and the **release schedule** as a Gantt on the epic ([release timeline in Jira](/blog/how-to-create-release-timeline-jira.md)). Three diagram types, three questions, one Confluence space.

## FAQ[​](#faq "Direct link to FAQ")

**Does Confluence have a built-in CI/CD diagram tool?** No — Confluence has no native diagramming. Mermaid Plus for Confluence renders `flowchart` and `gitGraph` from editable code blocks with a live preview.

**How do I show a quality gate in a Mermaid pipeline diagram?** Use a decision diamond on the arrows between stages — 'Security scan? → clean: deploy / vulnerabilities: block'. The reader sees the gate exactly where the pipeline gates.

**Can a Mermaid pipeline diagram show retries and rollbacks?** Yes. Draw a retry as a node pointing back at the stage it retries, and a rollback as a path from the deploy stage back to the previous release tag. See example 2.

**Should a pipeline diagram be a flowchart or a gitGraph?** Flowchart for pipeline logic (stages, gates, branches); gitGraph for release history (which commit became which tag). Most teams keep one of each.

Render every Mermaid diagram type — flowcharts, gitGraph, Gantt, ER and 25 more — in [Mermaid Plus for Confluence](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence/), free for up to 10 users.

Try <!-- -->Mermaid Plus for Confluence

All 29 Mermaid diagram types with live preview and one-click templates — free for up to 10 users.

[Get it on the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence)

## Related guides

* [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md)
* [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md)
* [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md)
* [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md)
* [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md)

Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links)

**Tags:**

* [confluence](/blog/tags/confluence.md)
* [mermaid](/blog/tags/mermaid.md)
* [ci-cd](/blog/tags/ci-cd.md)
* [devops](/blog/tags/devops.md)
* [flowchart](/blog/tags/flowchart.md)
* [gitgraph](/blog/tags/gitgraph.md)
* [how-to](/blog/tags/how-to.md)