How to Create CI/CD Pipeline Diagrams with Mermaid.js

# How to Create CI/CD Pipeline Diagrams with Mermaid.js

CI/CD pipelines are the backbone of modern software delivery. But explaining a pipeline to a new team member or documenting it for an architecture review? That's where a clear diagram beats a wall of YAML every time.

Mermaid.js lets you create CI/CD pipeline diagrams as code — no drag-and-drop tools, no image files to keep updated. Just text that lives alongside your pipeline config.

In this guide, you'll learn how to diagram real-world CI/CD workflows using Mermaid flowcharts, sequence diagrams, and more.

Why Diagram Your CI/CD Pipeline?

Pipeline configs (GitHub Actions YAML, Jenkinsfiles, .gitlab-ci.yml) describe *what* happens, but they're hard to scan visually. A diagram answers questions instantly:

- What runs in parallel vs. sequentially?

- Where are the approval gates?

- What happens on failure?

- Which environments get deployed to?

Mermaid diagrams stay in sync because they live in your repo — right next to the pipeline config they describe.

Basic CI/CD Pipeline Flowchart

Let's start with a simple build-test-deploy pipeline:

graph LR
    A[Push to main] --> B[Build]
    B --> C[Unit Tests]
    C --> D[Integration Tests]
    D --> E[Deploy to Staging]
    E --> F{Manual Approval}
    F -->|Approved| G[Deploy to Production]
    F -->|Rejected| H[Rollback]

This gives you a left-to-right flow that anyone can understand at a glance. The diamond shape for manual approval makes the decision point obvious.

Parallel Stages with Subgraphs

Real pipelines run jobs in parallel. Mermaid subgraphs are perfect for grouping parallel stages:

graph TD
    A[Code Push] --> B[Build Docker Image]
    B --> C[Push to Registry]
    C --> D[Run Tests]
    
    subgraph Tests [Parallel Test Suite]
        D --> E[Unit Tests]
        D --> F[E2E Tests]
        D --> G[Security Scan]
        D --> H[Lint & Format]
    end
    
    E --> I[All Passed?]
    F --> I
    G --> I
    H --> I
    I -->|Yes| J[Deploy Staging]
    I -->|No| K[Notify Team]

The subgraph labeled "Parallel Test Suite" visually groups the jobs that run concurrently, making it clear which steps block deployment.

GitHub Actions Workflow Diagram

Here's how to diagram a typical GitHub Actions workflow with multiple jobs:

graph TD
    A[PR Opened] --> B[Lint Job]
    A --> C[Test Job]
    A --> D[Build Job]
    
    B --> E{All Checks Pass?}
    C --> E
    D --> E
    
    E -->|Yes| F[Merge to main]
    F --> G[Build & Push Image]
    G --> H[Deploy to EKS Staging]
    H --> I[Run Smoke Tests]
    I -->|Pass| J[Deploy to EKS Production]
    I -->|Fail| K[Alert on Slack]

This maps directly to how GitHub Actions jobs depend on each other, making it easy to compare the diagram against your workflow YAML.

GitLab CI Pipeline Stages

GitLab CI pipelines are organized in stages. Here's a multi-stage deployment diagram:

graph LR
    subgraph Build Stage
        A[compile] --> B[docker-build]
    end
    
    subgraph Test Stage
        C[unit-test]
        D[sast-scan]
        E[dependency-check]
    end
    
    subgraph Deploy Stage
        F[deploy-staging]
        G[deploy-production]
    end
    
    B --> C
    B --> D
    B --> E
    C --> F
    D --> F
    E --> F
    F --> G

Each subgraph maps to a GitLab CI stage, and the arrows show job dependencies — exactly matching the needs: keyword in your .gitlab-ci.yml.

Deployment Pipeline with Rollback

For production deployments, you need to show the rollback path:

graph TD
    A[Release Tagged] --> B[Build Artifacts]
    B --> C[Deploy to Canary 5%]
    C --> D{Metrics OK?}
    D -->|Yes| E[Roll out to 25%]
    E --> F{Metrics OK?}
    F -->|Yes| G[Roll out to 100%]
    F -->|No| H[Rollback to Previous]
    D -->|No| H
    H --> I[Post-mortem]
    G --> J[Monitor 24h]

This canary deployment diagram shows progressive rollout percentages and the rollback path — critical for communicating deployment strategy to stakeholders.

Sequence Diagram for Deployment Approval

Sometimes a sequence diagram better captures the interaction between people and systems:

sequenceDiagram
    participant Dev as Developer
    participant CI as CI Server
    participant QA as QA Team
    participant Prod as Production
    
    Dev->>CI: Push to release branch
    CI->>CI: Build & Test
    CI->>QA: Deploy to staging
    QA->>QA: Run acceptance tests
    QA->>Dev: Approve / Request changes
    Dev->>CI: Trigger production deploy
    CI->>Prod: Blue-green deployment
    Prod->>CI: Health check OK
    CI->>Dev: Deployment successful

This shows who is involved at each stage — useful for runbooks and on-call documentation.

Styling Your Pipeline Diagrams

Make critical paths and failure states stand out with Mermaid styling:

graph LR
    A[Build] --> B[Test]
    B --> C[Deploy]
    C --> D[Production Live]
    B --> E[Failed]
    
    style D fill:#22c55e,stroke:#16a34a,color:#fff
    style E fill:#ef4444,stroke:#dc2626,color:#fff
    style A fill:#3b82f6,stroke:#2563eb,color:#fff

Green for success, red for failure, blue for in-progress — your team will instantly understand the pipeline state.

Best Practices for CI/CD Diagrams

1. Keep it high-level — Don't diagram every shell command. Focus on stages and decision points.
2. Use subgraphs for parallel work — Group concurrent jobs visually.
3. Show the unhappy path — Rollbacks, failures, and alerts are just as important as the happy path.
4. Put diagrams in your README — GitHub and GitLab both render Mermaid natively in markdown.
5. Update with the pipeline — When you change your CI config, update the diagram in the same PR.

Where to Use These Diagrams

• README.md — GitHub and GitLab render Mermaid automatically
• Architecture Decision Records (ADRs) — Document why your pipeline works this way
• Onboarding docs — New engineers understand the deploy process in seconds
• Incident runbooks — Show the rollback path clearly

Conclusion

Mermaid.js turns CI/CD pipeline documentation from a chore into something that actually stays maintained. Because the diagram is text, it can be reviewed in PRs, diffed, and updated alongside the pipeline config it describes.

Start with a simple flowchart of your main pipeline, then expand to cover parallel stages, approval gates, and rollback paths.

Create your CI/CD pipeline diagram now →