Get started

Keep diagrams in sync in CI

How to fail a pull request whose diagram pictures no longer match their source, with the GitHub Action or the command line. It is for anyone who keeps Plotwork diagrams in Markdown or .diagram files in a repository.

For

GitHub Actions
GitHub

TL;DR

Question	Answer
What is checked?	Every `diagram` fence in the files you name: a fence with no picture under it, a picture whose source or renderer changed, and source with mistakes. `.diagram` files are checked for mistakes.
What runs the check on GitHub?	The action `plotwork-official/plotwork-action`, pinned by commit. The engine is bundled into it, so it installs nothing and needs no account, key, or token.
How does a failure show in a pull request?	Each stale fence and each mistake is an error annotation on its line in the Files changed tab, and the job summary lists the files with the command that fixes them.
How do I fix a failure?	Run the action with `command: sync` on the same files and commit the Markdown and the SVGs it writes, or run `npx -y @buun_group/plotwork@0.1.0-beta.13 sync` on your machine.
What else can the action do?	`sync` redraws in the workspace and commits nothing, `validate` reports mistakes only, `render` draws `.diagram` files to SVG, and `generate` makes diagrams from Terraform, OpenAPI, Compose and other files and fails or opens a pull request when they drift (section 5).
What about other CI?	The command line runs the same check: `npx -y @buun_group/plotwork@0.1.0-beta.13 sync --check "docs/*/.md"`. See CI usage.
Does the check send my diagrams anywhere?	No. The action and the command line count nothing and, by default, make no request. Either can read an organisation's saved style rules when you name the organisation, and `generate` in write mode talks to GitHub to push and open a pull request, and to Plotwork only with `publish: true`. Both read your repository settings file on the machine they run on.

1. Check every pull request

Copy this workflow to .github/workflows/plotwork.yml:

1name: plotwork2
3on:4  pull_request:5    paths: ['**/*.md', '**/*.diagram']6
7permissions:8  contents: read9
10jobs:11  diagrams:12    runs-on: ubuntu-latest13    steps:14      - uses: actions/checkout@v715        with:16          persist-credentials: false17      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1418        with:19          paths: |20            README.md21            docs/**/*.md

The samples pin the latest release of the Action by its commit. @v1 becomes available at the first stable release.

With no paths, the action reads every Markdown file in the repository. A line in paths that starts with ! leaves out what it matches, such as !docs/drafts/**. Pin actions/checkout to a full commit SHA too, as you would any third-party action.

A stale diagram looks like this in the log, and as an error on line 12 of the file in the pull request:

::error file=docs/architecture.md,line=12,title=Stale diagram::The picture under this diagram is missing or out of date.%0AFix: run plotwork-official/plotwork-action@v1.0.0-beta.14 with command: sync, then commit the Markdown file and the SVG files.

The job summary gives the same fix: run the action with command: sync and the same paths, then commit what it wrote. Once the command line is on npm, the summary and the annotation also give an npx command that pins the version built from the same engine as the action, so the pictures it draws pass the check.

2. The commands

`command`	Reads	Writes	Fails when
`check` (default)	`paths` and `diagrams`	Nothing	A picture is missing or stale, or a diagram has an error
`sync`	`paths`	The Markdown files and their SVGs, in the workspace	A diagram has an error
`validate`	`paths` and `diagrams`	Nothing	A diagram has an error, or a warning with `fail-on: warning`
`render`	`diagrams`	A light and a dark SVG per `.diagram` file, in `out-dir`	A diagram has an error
`generate`	The `sources` of the settings file	Nothing with `mode: check`; with `mode: write`, the diagrams, then a pull request or a commit	A diagram drifted from its files (check mode), or a diagram has an error

Redraw and open a pull request

sync redraws the stale pictures in the runner's workspace and commits nothing; it never holds a token. To commit from a workflow, give the write permissions to the job and add a step that commits, such as peter-evans/create-pull-request:

1name: plotwork-sync2
3on:4  push:5    branches: [main]6    paths: ['**/*.md']7
8permissions:9  contents: read10
11jobs:12  sync:13    runs-on: ubuntu-latest14    permissions:15      contents: write16      pull-requests: write17    steps:18      - uses: actions/checkout@v719        with:20          persist-credentials: false21      - id: plotwork22        uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1423        with:24          command: sync25          paths: docs/**/*.md26      - if: steps.plotwork.outputs.stale != '0'27        uses: peter-evans/create-pull-request@v828        with:29          branch: plotwork/sync30          commit-message: 'docs: redraw stale diagrams'31          title: 'docs: redraw stale diagrams'32          add-paths: docs/**

The repository must allow GitHub Actions to create pull requests (Settings, Actions, General). Most teams keep check on pull requests and run the sync locally.

Report mistakes only

1- uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.142  with:3    command: validate4    diagrams: diagrams/**/*.diagram5    fail-on: warning

Draw `.diagram` files

1- uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.142  with:3    command: render4    diagrams: diagrams/**/*.diagram5    out-dir: build/diagrams

diagrams/flow.diagram becomes build/diagrams/diagrams/flow.svg and flow.dark.svg. Each SVG carries its source, so Editing an existing diagram works on it.

3. Inputs and outputs

Input	Default	Meaning
`command`	`check`	`check`, `sync`, `validate`, `render`, or `generate`.
`paths`	`*/.md`	Markdown files: one glob, file, or folder per line. `node_modules` and `.git` are never searched.
`diagrams`	`*/.diagram`	`.diagram` files, in the same form. Set it to `''` for none.
`out-dir`	`plotwork-svg`	Where `render` writes, inside the repository.
`fail-on`	`error`	`error`, `warning`, or `never`. Problems are annotated either way.
`convert-mermaid`	`false`	When `true`, `check` and `sync` treat each `mermaid` fence that converts as a diagram. See Migrating from Mermaid.
`config`	empty	The repository settings: header defaults every command applies, and rules `check` and `validate` apply. Empty looks for `plotwork.config.json`, then `.plotwork/config.json`, from `working-directory` up to the repository root; `off` reads none.
`rules-org`	empty	An organisation whose saved style rules to apply instead of the file's rules, read with the key in `PLOTWORK_API_KEY`.
`mode`, `on-drift`, `pr-branch`, `pr-title`, `commit-message`, `publish`, `github-token`		`generate` only. See Diagrams as code, section 7.
`summary`	`true`	Write the job summary.
`working-directory`	`.`	The folder to run in. Annotations still name files from the repository root.

Output	Meaning
`stale`	Diagrams whose picture was missing or out of date.
`errors`, `warnings`	The problems found.
`files`	A JSON array: the files that need a sync (`check`), the files written (`sync`, `render`), or the files with an error (`validate`).
`pull-request`, `published`	`generate` only: the pull request it opened or edited, and what it published.

check, validate, and render need only contents: read. generate in check mode does too; in write mode it needs contents: write, and pull-requests: write to open a pull request.

4. The command line

The npm package @buun_group/plotwork holds the bin plotwork, built from the same engine as the action. It runs the same check on any CI, as one command with an exit code:

npx -y @buun_group/plotwork@0.1.0-beta.13 sync --check "docs/**/*.md"

Pin the version, so a new release cannot change your build without a change you review. The CLI tab has every command, with the pipeline for GitLab CI, Azure Pipelines, Jenkins, and CircleCI, the exit codes and output formats, and the command reference.

5. Diagrams made from files

When a diagram is made from files of the repository, such as a Terraform stack or an OpenAPI document, name it in sources in the settings file, and let generate keep it in step. The full guide is Diagrams as code.

A pull request check

1name: diagrams2
3on:4  pull_request:5
6permissions:7  contents: read8
9jobs:10  drift:11    runs-on: ubuntu-latest12    steps:13      - uses: actions/checkout@v714        with:15          persist-credentials: false16      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1417        with:18          command: generate

Regenerate on main and open a pull request

1name: diagrams-regenerate2
3on:4  push:5    branches: [main]6  schedule:7    - cron: '0 4 * * *'8
9permissions:10  contents: read11
12jobs:13  regenerate:14    runs-on: ubuntu-latest15    permissions:16      contents: write17      pull-requests: write18    steps:19      - uses: actions/checkout@v720      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1421        with:22          command: generate23          mode: write

The repository must allow GitHub Actions to create pull requests (Settings, Actions, General). A pull request opened with the workflow's own token starts no workflow; pass a GitHub App or personal token in github-token to have its checks run.

Publish to an organisation

1name: diagrams-publish2
3on:4  push:5    branches: [main]6
7permissions:8  contents: read9
10jobs:11  publish:12    runs-on: ubuntu-latest13    permissions:14      contents: write15      pull-requests: write16    steps:17      - uses: actions/checkout@v718      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1419        with:20          command: generate21          mode: write22          publish: true23        env:24          PLOTWORK_API_KEY: ${{ secrets.PLOTWORK_API_KEY }}

Each source with a publish section, such as { "organization": "acme", "folder": "Platform" }, is published with the organisation key in the secret. Only the generated diagram source is sent, never the files it was made from.

Page	Why
Markdown and GitHub	What a sync writes and why the pictures are committed
Migrating from Mermaid	Convert existing Mermaid fences first
Repository settings	Defaults for every header, and rules a pull request must pass
Diagrams as code	Diagrams made from Terraform, OpenAPI, Compose and other files, kept in step
Slack, email, Confluence, and Notion	Share a picture outside the repository
Local usage sharing	What the MCP package can count, which the command line and the action never do