Mermaid for CI/CD pipelines: visualize build workflows

CI/CD pipelines are complex. A commit triggers tests, builds, deployments across staging and production, and approval gates. Most teams document this in a wiki or a word doc that drifts within weeks. Mermaid flowcharts let you show the entire pipeline in plain text — version-controlled, updated in the same PR as the pipeline change, and rendering everywhere from GitHub to Notion.

Why diagram your pipeline?

A visual pipeline helps onboard new team members and catches design flaws before they cause outages:

• Where are the approval gates?
• What runs in parallel vs. serial?
• How long does a typical deployment take?
• What happens if a test or build fails?
• Which secrets or credentials does each stage need?

A diagram forces clarity. You can't draw a CI/CD pipeline and simultaneously have a confused policy about what requires approval.

Simple linear pipeline

Here's a basic pipeline: push code, run tests, build, deploy to staging:

flowchart LR
    A["📝 Developer pushes code"] --> B["🧪 Run unit tests"]
    B --> C{"Tests pass?"}
    C -->|No| E["❌ Notify Slack"]
    C -->|Yes| D["🏗️ Build Docker image"]
    D --> F["🚀 Deploy to staging"]
    F --> G["✅ Smoke tests"]
    G --> H{"Tests pass?"}
    H -->|No| I["❌ Block production"]
    H -->|Yes| J["🟢 Ready for production"]
    E --> K["🔧 Developer fixes"]
    K --> B

This is readable at a glance: tests run first, block the build if they fail. The build only happens if tests pass. Staging smoke tests gate production promotion.

Multi-stage pipeline with approval gates

Production deployments usually require human approval. Here's a more realistic flow:

flowchart LR
    A["Push to main"] --> B["Lint & type check"]
    B --> C{"Pass?"}
    C -->|No| D["Fail, notify"]
    D --> E["Developer fixes"]
    E --> A
    
    C -->|Yes| F["Run tests"]
    F --> G{"Pass?"}
    G -->|No| D
    
    G -->|Yes| H["Build image"]
    H --> I["Push to registry"]
    
    I --> J["Deploy to staging"]
    J --> K["Run E2E tests"]
    K --> L{"Pass?"}
    L -->|No| D
    
    L -->|Yes| M["🔑 Await approval"]
    M --> N{"Approved?"}
    N -->|No| O["Cancelled"]
    N -->|Yes| P["Deploy to production"]
    P --> Q["Smoke tests"]
    Q --> R{"Pass?"}
    R -->|No| S["🚨 Rollback"]
    R -->|Yes| T["✅ Live"]

The approval gate at "await approval" is critical — without it, flawed code can reach customers. The rollback path from "production smoke tests" shows what happens when production tests fail.

Parallel jobs

Most CI/CD systems run independent jobs in parallel. Mermaid supports this with multiple paths that reconverge:

flowchart LR
    A["Code pushed"] --> B["Start"]
    
    B --> C["Unit tests"]
    B --> D["Lint"]
    B --> E["Type check"]
    
    C --> F{"All pass?"}
    D --> F
    E --> F
    
    F -->|No| G["Fail"]
    F -->|Yes| H["Build"]
    H --> I["Deploy staging"]
    I --> J["Done"]

Parallel jobs run simultaneously, reducing the total time for the pipeline. Without the diagram, new team members don't know which jobs can run concurrently and which depend on each other.

Pipeline with manual and automated gates

Real pipelines mix automated checks with manual decisions:

flowchart LR
    A["PR opened"] --> B["🤖 Lint & type check"]
    B --> C["🤖 Run tests"]
    C --> D["🤖 Build"]
    D --> E{"Tests & build\npass?"}
    
    E -->|No| F["❌ Block merge"]
    E -->|Yes| G["👤 Code review"]
    G --> H{"Approved?"}
    H -->|No| I["Request changes"]
    I --> J["Developer updates"]
    J --> C
    
    H -->|Yes| K["Auto-merge to main"]
    K --> L["Deploy staging"]
    L --> M["E2E tests pass?"]
    M -->|No| N["Alert team"]
    M -->|Yes| O["👤 Deploy approval"]
    O --> P["Approved?"]
    P -->|No| Q["Stay on staging"]
    P -->|Yes| R["Deploy production"]
    R --> S["✅ Live"]

This diagram shows engineers exactly when to expect a prompt from the CI system (code review approval) and when to wait for manual approval (production deploy).

Practical patterns

Feature branch workflow:

flowchart LR
    A["Feature branch push"] --> B["Run full test suite"]
    B --> C{"Pass?"}
    C -->|No| D["Fix in PR"]
    D --> B
    C -->|Yes| E["Code review"]
    E --> F{"Approved?"}
    F -->|No| D
    F -->|Yes| G["Squash merge to main"]
    G --> H["Main branch tests"]
    H --> I["Deploy staging"]
    I --> J["Ready for release"]

Blue-green deployment:

flowchart LR
    A["Deploy to green env"] --> B["Run tests on green"]
    B --> C{"Pass?"}
    C -->|No| D["Fix & rebuild"]
    D --> A
    C -->|Yes| E["Health checks on green"]
    E --> F{"Ready?"}
    F -->|No| D
    F -->|Yes| G["Switch traffic: green"]
    G --> H["Monitor"]
    H --> I{"Errors?"}
    I -->|Yes| J["Switch back to blue"]
    I -->|No| K["✅ Deployment done"]

Release candidate promotion:

flowchart LR
    A["Tag release candidate"] --> B["Build signed artifacts"]
    B --> C["Deploy RC to staging"]
    C --> D["Manual QA testing"]
    D --> E{"QA approves?"}
    E -->|No| F["Fix bugs on main"]
    F --> A
    E -->|Yes| G["Approval for production"]
    G --> H["Deploy to production"]
    H --> I["Post-deploy monitoring"]
    I --> J["Release notes published"]

Keeping pipelines documented

Document it once. Create docs/deployment.md with the pipeline diagram. Link it from the README.

Update it when you change it. A PR that changes .github/workflows/deploy.yml should also update docs/deployment.md. Pipeline changes deserve review like code changes do.

Use it for onboarding. New engineers should read the pipeline diagram before their first deployment. It answers the question "what happens when I merge to main?" without forcing them to decode YAML.

Pipeline visualization tools

Mermaid is great for static documentation. If you also need real-time pipeline status, consider:

• GitHub Actions: Visual workflow UI in the PR
• GitLab CI: Pipeline graph view
• Jenkins: Blue Ocean UI
• ArgoCD: Application deployment visualization

These show live status; Mermaid shows the design. Both matter.

FAQ

Q: Should I include every step, or just the high-level flow? A: Diagram the flow your team thinks about. If developers ask "do I need to wait for the database migration before the app deploys?" the answer goes in the diagram. Don't include the 10 linter passes; group them as one "lint" step.

Q: How do I show conditional logic based on branch (e.g., staging if PR, production if main)? A: Write the common path clearly, then note branch-specific behavior in prose. "This diagram shows main; feature branches skip the production approval gate."

Q: Where does the pipeline diagram live? A: In docs/ alongside a README that explains the stages. Link it from your deployment runbook and from the top-level README.

Q: Can I auto-generate the diagram from my pipeline YAML? A: There are tools for GitHub Actions and GitLab CI, but manual diagrams are easier to keep current and easier to reason about. A 20-minute refresh beats a stale auto-generated diagram.

Document your team's deployment pipeline in the MermaidCreator editor, then commit it to your repo so every PR viewer knows exactly what happens next.