The Plotwork GitHub App
The Plotwork GitHub App turns on diagrams as code in your organisation's repositories from the portal. Install it on a GitHub account, link it to your Plotwork organisation, and the Drift tab lists your repositories with the formats Plotwork can draw from. Enable opens one pull request per repository with the settings file, the drift check workflow and the first diagrams, and sets up the trusted publisher that signs the workflow in with no key.
- GitHub
TL;DR
| Question | Answer |
|---|---|
| Which plan? | Pro and Enterprise, the plans with the drift dashboard. |
| Who can set it up? | The organisation's owner or an admin. Members see the installations and each repository's status. |
| Where? | The organisation's Drift tab, the GitHub card. |
| What does the App ask GitHub for? | Read metadata; write contents, pull requests, checks and workflows. It only ever writes the branch plotwork/setup and opens a pull request from it. |
| What does Enable add? | plotwork.config.json, .github/workflows/diagrams.yml, and the diagrams in docs/diagrams/, in one pull request. Nothing reaches your default branch until you merge it. |
| How does CI sign in? | As a trusted publisher made with the pull request, pinned to the repository's GitHub ids. Until the pinned Action signs in by itself, the workflow reads PLOTWORK_API_KEY and the pull request says so. |
| What does Plotwork store? | The installation's and repositories' ids and names, the formats found, and each repository's status. No token, no path and no file of yours. |
| Can someone link my installation to their organisation? | No. Linking needs proof, through GitHub, that the person signed in can reach the installation, and one installation belongs to one organisation. |
1. Connect GitHub
- Open the organisation in the portal and choose the Drift tab.
- On the GitHub card, choose Connect GitHub. GitHub asks you to authorise Plotwork, and sends you back to the portal with the installations of the App your GitHub account can reach. An App installed earlier, by you or someone else in your GitHub organisation, needs no reinstall.
- Choose the installation and the Plotwork organisation, and choose Link. Only organisations you own or administer are offered.
- The page says what was linked, with a button to the Drift tab.
When your GitHub account can reach no installation yet, the page offers Install the App on GitHub. Install on another account on the card does the same from the start: GitHub asks which account to install the App on and which repositories it may reach, all of them or the ones you choose, then sends you back to link it.
| The page says | What to do |
|---|---|
| This GitHub sign-in has expired or was used already | Choose Link again. A sign-in from GitHub works once and for a few minutes; Link again gets a new one, and the App stays installed. |
| The GitHub account cannot reach that installation | Choose Sign in as another GitHub account, and pick an account that can. |
| The installation is linked to another Plotwork organisation | Unlink it there first. |
| Installation requested | An owner of that GitHub organisation must approve the App. Then choose Connect GitHub again. |
Plotwork reads the repositories the installation can reach, 100 at a time. Choose Refresh repositories after you change the App's repositories on GitHub; Plotwork also hears of the change from GitHub on its own.
2. Look at what Plotwork found
Each repository shows icons for the formats its files suggest:
| Format | What Plotwork looks for |
|---|---|
| Terraform, Bicep | A folder of .tf or .bicep files |
| OpenAPI, AsyncAPI | openapi.yaml, swagger.json, *.openapi.yaml, asyncapi.yaml |
| Compose | docker-compose.yml, compose.yaml |
| Kubernetes, Helm, Kustomize | A k8s, kubernetes, manifests or deploy folder; a chart's Chart.yaml; a kustomization.yaml |
| SQL, Prisma | schema.sql, a migrations folder of .sql files, schema.prisma |
| CI pipelines | .github/workflows/*.yml, .gitlab-ci.yml, azure-pipelines.yml |
| Catalogs | catalog-info.yaml (Backstage), workspace.dsl (Structurizr) |
| GraphQL, Protocol Buffers | A folder of .graphql or .graphqls files, or of .proto files |
| Serverless, Dockerfiles, nginx | serverless.yml; every Dockerfile, *.Dockerfile and Containerfile; an nginx.conf with its conf.d |
| dbt, workspaces | A dbt_project.yml with its models, seeds and snapshots; a root package manifest with pnpm-workspace.yaml or packages below it |
Only the paths are read to find them, and installed, built, vendored and test folders are skipped. At most eight diagrams a repository, the largest first.
3. Enable a repository
Choose Enable beside a repository, or tick several and choose Enable chosen. Plotwork:
- reads the files the diagrams are drawn from, at most 24 files and 1 MiB,
- draws the diagrams with the same generator
plotwork generateruns, - commits the settings file, the workflow and the diagrams to the branch
plotwork/setup, - opens a pull request titled "Add Plotwork diagrams and the drift check" that lists each diagram and the files it is drawn from,
- adds a trusted publisher for
diagrams.ymlin that repository, under Keys and CI.
A repository that uses Plotwork already
Enable never overwrites a setup. Before you choose Enable, the row says what it will do:
| The row says | Enable does |
|---|---|
| Adds 1 source and drift reporting to your existing setup | One pull request with only the additions: the sources none of yours reads already, added at the end of sources with nothing else in the file changed, and report-drift: true and id-token: write in your own workflow when its pin of the Action is v1.2.0 or later. The pull request lists what it adds and what it left as it is. |
| Already set up: registers CI only | No pull request. Plotwork adds the trusted publisher for your own workflow file, and the row reads "Set up, waiting for a run" until the first drift report arrives. |
| The file does not check. Enable opens a pull request that fixes it | Choose Open a PR that fixes it. The pull request on plotwork/fix-config carries the fixed file alone, with a table of each fix (line, before and after, why) and what needs you, such as a source that reads no file, which is kept. Once it merges, choose Enable again for the rest. |
| The file does not check, so Enable leaves it alone | No fix is plain enough to make for you. The row shows each problem with its line, column and a hint. Fix the file and Enable again. |
A workflow pinned to an older Action, or one with no permissions: block, is left as it is, and the row and the pull request suggest the change instead. Register CI only, on a row whose file does not check, lets CI sign in while the file is fixed.
The fix never removes a source or a setting. It reads comments, trailing commas, single quotes and the like as an editor would and writes strict JSON in your file's own indentation and key order, renames a key a typo away from a known one, maps a value a typo away from an allowed one, and makes repeated names unique; anything it cannot fix plainly is left and listed.
Enable chosen enables one repository at a time, a second apart, as GitHub asks of tools that write. When GitHub asks Plotwork to slow down, the card waits as long as GitHub says and goes on.
Review the pull request as any other: change a source's name or files in plotwork.config.json, or delete a diagram you do not want, and the check redraws to match.
4. Follow each repository
| Status | Means |
|---|---|
| Not enabled | No pull request yet. |
| Pull request open | The setup pull request is waiting for review. |
| Merged | Merged; no drift run has been reported since. |
| Reporting | The latest drift run since it was enabled was in step. |
| Failing | The latest drift run drifted or failed: open the Drift card below for the details. |
| Closed | The pull request was closed without merging. Enable opens a new one. |
| Fix PR open | A pull request that fixes the settings file is open. When it closes, the row is scanned again and says what Enable does next. |
| Set up, waiting for a run | The repository was set up already, so Enable registered CI with no pull request. The next drift report makes it Reporting or Failing. |
5. Remove it
| To | Do |
|---|---|
| Stop one repository | Revert the pull request's files, and remove its trusted publisher under Keys and CI. |
| Unlink an installation | Choose Unlink on the GitHub card. Plotwork forgets its repositories. The App stays installed on GitHub. |
| Uninstall the App | Choose Settings on GitHub beside the installation, then Uninstall. Plotwork removes the link when GitHub tells it. |
Every link, unlink, uninstall, suspension and Enable is in the organisation's audit log as orgs.github.link, orgs.github.unlink, orgs.github.uninstalled, orgs.github.suspended, orgs.github.unsuspended and orgs.github.enable.
6. What Plotwork keeps
| Kept | Not kept |
|---|---|
| The installation's id, account and repository selection | Any GitHub token: the App's tokens live an hour in memory, and the token GitHub gives for your sign-in is revoked at once |
| Each repository's id, name, default branch and whether it is private | The repository's tree and paths |
| The format names a scan found, and when | The content of any file: read during Enable to draw the diagrams, then forgotten |
| Each repository's status and its pull request's number | The diagrams themselves: they are in your repository, not in Plotwork |
| The id of each webhook delivery, for seven days, so one is never applied twice | The webhook's payload |
Unlinking removes the installation's rows, and deleting the organisation removes all of them.
7. Troubleshooting
| The card says | Why, and what to do |
|---|---|
| The App is not set up on this server | The server has no App configured. Plotwork's hosted service has one; a self-hosted engine does not. |
plan.github_app_not_included | The owner's plan has no drift dashboard. Links made before stay and can be removed. |
github.installation_not_yours | The GitHub account you signed in with cannot reach that installation. Sign in to GitHub as someone who can. |
github.installation_linked | Another Plotwork organisation linked it. Unlink it there first. |
github.config_invalid | The repository's plotwork.config.json does not check. Fix each problem the row shows, then Enable again; Register CI only works meanwhile. |
github.nothing_to_draw | No file Plotwork reads could be drawn. Write the settings file by hand to name the files. |
github.suspended | The App is suspended for that account on GitHub. Unsuspend it there. |
github.rate_limited | GitHub asked to wait. Enable chosen waits on its own; try a single Enable again later. |
See also
| Page | Why |
|---|---|
| Trusted publishers | How CI signs in with no key |
| The drift dashboard | The reports the status reads |
| Compliance evidence | Each repository's diagrams as evidence for audit controls, and the Mermaid scan through the App |
| Keep diagrams in sync in CI | The Action's commands and inputs |
| Repository settings | What plotwork.config.json holds |
| Audit log | The events the App records |
| Privacy policy | What is stored, and for how long |