GitOps Mermaid Patterns

Field	Value
Type	Skill Resource
Source	`~/.copilot/skills/technical-writing/references/mermaid/gitops-patterns.md`
Description	Not specified

Source Content

GitOps Mermaid Patterns

These patterns apply the diagram principles to GitOps flows, with the color and renderer specifics for beautiful-mermaid.

Group first: people vs. automation

The GitOps docs are written for readers asking “where am I in this process, and what do I have to do versus what happens to me?” The answer is a grouping, not an actor node. Group the flow by what people do vs. automation — the most important boundary in a delivery diagram. Actors are implied by the What people do group or named on an edge label; they are never their own nodes (see principle 2).

flowchart LR
  subgraph People["What people do"]
    PR["Open PR"] --> Review["Review"] --> Merge["Merge to main"]
  end
  subgraph Auto["Automation"]
    Build["Build & scan"] --> Deploy["ArgoCD sync"] --> Verify["Health check"]
  end
  People -->|on merge| Auto

The reader sees instantly that everything on the left is theirs to do and everything on the right happens on its own. That is the lesson; the labels are secondary.

When you do need to name a person — on an edge label, or as an actor in a sequence diagram — use canonical labels consistently:

Role	Label	Avoid
Developer	`Developer`	`Dev`, `Author`, `Engineer`, `User`
Reviewer	`Reviewer`	`Rev`, `Approver`, `Peer`
Release Manager	`Release Manager`	`RM`, `Deployer`
Incident Lead	`Incident Lead`	`IC`, `Incident commander`, `On-call`
Platform Owner	`Platform Owner`	`PO`, `Org admin`, `Admin`

Renderer Constraint

beautiful-mermaid flowcharts support direct node styling. Use it to accent the boundary or the punchline, not to color every box:

flowchart TD
  subgraph People["What people do"]
    PR["Open PR"] --> Gate{"Approved?"}
  end
  subgraph Auto["Automation"]
    Merge["Merge to main"] --> Pipeline["CI pipeline"]
  end
  Gate -->|Yes| Merge
  Gate -->|No| PR

  style Gate fill:#fef9c3,stroke:#ca8a04,color:#422006
  style Merge fill:#dcfce7,stroke:#16a34a,color:#14532d

Do not use classDef or class in beautiful-mermaid flowcharts. This renderer can expose a stray visible class node. Use direct style Node ... lines.

Sequence diagrams support actor, but this renderer cannot color individual actors. Use sequence diagrams when strict message order matters more than the people/automation grouping.

Color Palette

Color teaches, it does not decorate (principle 7). Reserve it for three things: the people/automation boundary, the diagram’s punchline node, and success/failure outcomes. A diagram with eight colored boxes stops being readable — when in doubt, leave nodes neutral and accent only the box that carries the lesson.

Enforcement gates

Use red for hard blocks, yellow for fix-and-retry, and green for final success. Keep the success path as the spine and fan failures off the side.

Outcome	Fill	Stroke	Text
Hard block	`#fee2e2`	`#dc2626`	`#450a0a`
Fix and retry	`#fef9c3`	`#ca8a04`	`#422006`
Success	`#dcfce7`	`#16a34a`	`#14532d`

Neutral system / infrastructure nodes

Keep systems, services, queues, and infrastructure neutral so the accent colors keep their meaning.

Node type	Fill	Stroke	Text
Neutral process / system	`#f1f5f9`	`#475569`	`#0f172a`
Git / source control	`#f0fdf4`	`#16a34a`	`#14532d`
CI / GitHub Actions	`#fef3c7`	`#b45309`	`#451a03`
Kubernetes / cluster	`#eff6ff`	`#2563eb`	`#172554`
Observability / alerting	`#fdf4ff`	`#9333ea`	`#3b0764`
Database / store	`#fefce8`	`#ca8a04`	`#422006`

Sequence-diagram actor accents

When a sequence diagram names people, these role accents keep them distinct. They apply to sequence actors, not flowchart nodes (flowcharts have no actor nodes).

Role	Fill	Stroke	Text
Developer	`#dbeafe`	`#2563eb`	`#172554`
Reviewer	`#fef3c7`	`#d97706`	`#451a03`
Release Manager	`#ede9fe`	`#7c3aed`	`#2e1065`
Incident Lead	`#fee2e2`	`#dc2626`	`#450a0a`
Platform Owner	`#d1fae5`	`#059669`	`#064e3b`

System Node Shape Vocabulary

Hard rule: a multi-layer system/topology diagram (GitOps flow, CI/CD, infra pipeline) must give every distinct layer its own shape + muted color pair. A diagram where every node is the same rectangle and the same fill is a defect — the reader can’t tell a durable store from a control plane from a manual gate at a glance, which is exactly the problem this shape vocabulary exists to fix.

Layer / role	Shape	Syntax	Notes
Actor / pipeline endpoint	Circle	`(( ))`	Only the person or system that starts or receives the pipeline — not intermediate work steps. The one flowchart exception to “no actor nodes.”
Process / environment	Rectangle	`[ ]`	Default shape for systems, services, and environment stages (Test, Staging, Production).
Durable store / source of truth	Cylinder	`[( )]`	Git repos, databases, artifact registries — anything the system reads from or writes to persistently.
Control plane / manual gate	Hexagon	`{{ }}`	Reconcilers (ArgoCD) and manual-approval checkpoints both get a hexagon — they’re both “decision points that aren’t a simple branch.” Distinguish them by color, not shape.
Ephemeral / optional	Any shape, dashed border	`stroke-dasharray`	Preview environments, feature flags, anything that isn’t part of the durable promotion line.

Reserve the diamond { } for a literal yes/no branch (as in the enforcement-gate example above); use the hexagon for control-plane and gate nodes so the two are never visually confused.

Extended system node palette

Add these rows to the neutral palette above when a diagram needs to distinguish more than one system layer at a glance. Keep every fill muted (low saturation) — the point is legibility per layer, not decoration.

Node type	Shape	Fill	Stroke	Text
Actor / pipeline endpoint	`(( ))`	`#f4f0fa`	`#6d4fa3`	`#2b2440`
Source control / durable store	`[( )]`	`#eef2f7`	`#4a5b70`	`#22303f`
Control plane (reconciler)	`{{ }}`	`#eaf4ee`	`#2f7a52`	`#173926`
Runtime / cluster	`[ ]`	`#f6f0e6`	`#8a6a2f`	`#3d2f10`
Ephemeral (dashed)	any, dashed	`#f6f0e6`	`#8a6a2f`	`#3d2f10`
Promoted environment	`[ ]`	`#e8f1fb`	`#2f6096`	`#122c42`
Manual approval gate	`{{ }}`, dashed	`#fdeceb`	`#b6493a`	`#4a1c15`

Worked example — GitOps promotion topology

This is the pattern the palette above is built for: source, control plane, runtime, and a promotion line with an explicit manual gate before each environment that isn’t auto-deployed.

flowchart LR
    ENGINEER(("Engineer")):::actor
    GITHUB[("GitHub<br/>main")]:::source
    GITOPS{{"ArgoCD<br/>pulls &amp; reconciles"}}:::control
    K8S["Kubernetes"]:::runtime
    TEST["Test<br/>reflects main"]:::env
    GATE{{"Manual approval"}}:::gate
    PROD["Production"]:::env
    USER(("User")):::actor

    ENGINEER -->|merges| GITHUB
    GITOPS -.->|pulls, never pushed to| GITHUB
    GITOPS --> K8S
    K8S ==>|automatic, every merge| TEST
    TEST -->|same image, promoted| GATE --> PROD
    PROD --> USER

    classDef actor fill:#f4f0fa,stroke:#6d4fa3,color:#2b2440
    classDef source fill:#eef2f7,stroke:#4a5b70,color:#22303f
    classDef control fill:#eaf4ee,stroke:#2f7a52,color:#173926
    classDef runtime fill:#f6f0e6,stroke:#8a6a2f,color:#3d2f10
    classDef env fill:#e8f1fb,stroke:#2f6096,color:#122c42
    classDef gate fill:#fdeceb,stroke:#b6493a,stroke-dasharray:4 2,color:#4a1c15

Notice the diagram encodes two lessons in shape and color alone, before a single label is read: which nodes are people versus system nodes (circle vs. rectangle/hexagon), and which promotion step is automatic versus gated (a thick arrow into the only auto-deployed environment; a dashed red hexagon in front of every gated one). This is also how to show continuous delivery without continuous integration — style the auto-deployed environment’s inbound edge as a thick arrow, and give every environment that requires a person’s sign-off its own gate node in front of it. Never rely on an edge label alone (“approved by a person”) to carry that distinction; a reader skimming shapes and colors should get it without reading text.

Print-Safe Layout

Default to flowchart TD — it prints as a tall column that fits a page and a narrow browser. Reach for LR only when the path is a genuine left-to-right pipeline and direction carries the meaning. Keep the happy path near 5–7 nodes, and let subgraphs (not extra nodes) carry the structure. Avoid tall one-node-per-line chains that leave blank pages in PDF output.

Subgraph Zone Pattern

Subgraphs are the structure, not an afterthought — every flowchart gets them (principle 1). Beyond people/automation, zones can mark environments or stages when that boundary teaches the most:

flowchart LR
  subgraph local[Local workspace]
    Commit["git push"]
  end
  subgraph github[GitHub]
    PR["Open PR"] --> CI["CI checks"]
    CI -->|Pass| Merge["Squash merge"]
  end
  subgraph cluster[Kubernetes cluster]
    ArgoCD["ArgoCD sync"] --> Runtime["Running pods"]
  end
  Commit -->|reviewer approves| PR
  Merge --> ArgoCD

  style CI fill:#fef3c7,stroke:#b45309,color:#451a03
  style Merge fill:#dcfce7,stroke:#16a34a,color:#14532d
  style Runtime fill:#dcfce7,stroke:#16a34a,color:#14532d

Rules for subgraph zones:

Use subgraph id[Display label] — no colon after the label, no bare quoted string.
Label the boundary, short and place-like: Local workspace, GitHub, CI pipeline, Kubernetes cluster (principle 6).
Connect zones with short-labeled or unlabeled arrows so the zone boundary is the story.
Style nodes inside subgraphs the same as outside — style rules work anywhere.

Example Box Pattern

When teaching one correct format, group the person’s action and let an edge carry the gate. The actor is implied by the What people do zone, not drawn as a node:

flowchart TD
  subgraph People["What people do"]
    Msg["feat(profile): add language selector<br> <br>Refs: ADR-070"]
  end
  Msg --> Gate{"Conventional Commit?"}
  Gate -->|No| Fail["Blocked"]
  Gate -->|Yes| Ship["Ready"]

  style Fail fill:#fee2e2,stroke:#dc2626,color:#450a0a
  style Ship fill:#dcfce7,stroke:#16a34a,color:#14532d

Use <br> <br> with a space when a meaningful blank line must appear in an SVG node. Avoid this pattern unless the multiline example is the point.