Hosted diagrams and plans

The drift dashboard

The drift dashboard shows, in one place, which diagrams across an organisation's repositories still match the files they are drawn from. The GitHub Action finds drift in each repository by itself on every plan; with report-drift turned on, each run also sends what it found to the organisation's Drift tab in the portal.

For

GitHub Actions

TL;DR

Question	Answer
How do I turn it on?	Give the Action's `generate` step `report-drift: true` and an organisation key in `PLOTWORK_API_KEY`.
What is sent?	Metadata only: the repository, the ref, the commit, the event, the run and pull request links, and per diagram its name, path, status, change counts and CODEOWNERS owners. Never a diagram, a file, or the names of what changed.
Where do I read it?	The organisation's Drift tab in the portal. Every member can read it, readers included.
What narrows it?	Stale only (drifted or failed), and one owner or team, or the diagrams with no owner.
Which plan?	Pro and Enterprise. On Free a report is refused with a notice and nothing is stored; the check itself still runs.
How long is a run kept?	By the organisation owner's plan, in the table under How long runs are kept.
Can it fail my build?	No. A refused or unsent report is a notice in the log; the check's own result decides the exit code.

1. Turn on reporting

In the portal, open the organisation and choose the Keys tab. Make a key that can do diagrams ("Diagrams" or "Diagrams and the audit log"). A key made "Audit log only" cannot send a report, and a personal key is refused.
Store it as a repository or organisation secret named PLOTWORK_API_KEY.
Add report-drift: true to the step that runs generate, and pass the key to that step.

1name: diagrams2on:3  pull_request:4  push:5    branches: [main]6permissions:7  contents: read8jobs:9  check:10    runs-on: ubuntu-latest11    steps:12      - uses: actions/checkout@v713        with:14          persist-credentials: false15      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.1416        with:17          command: generate18          mode: check19          report-drift: true20        env:21          PLOTWORK_API_KEY: ${{ secrets.PLOTWORK_API_KEY }}

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

The run reports to the organisation named by the rules-org input, else by brand.organization in the repository's plotwork.config.json, else to the key's own organisation. Reporting works in check mode and in write mode. A pull request from a fork gets no secrets from GitHub Actions, so its run says the key is missing and reports nothing.

When the report is stored, the run logs a notice, "Sent to the drift dashboard", with a link to the organisation's Drift tab.

2. What is sent

The Action builds the report from the run's own result and leaves everything else out. The diagram is compared with its files on the machine that runs the job; only the outcome travels.

Sent	Not sent
The repository's `owner/name`, the git ref, the commit, the event	A diagram's source or picture
Links to the run and to the pull request	A file's content, or a path a source reads
For each diagram: its name from the settings, its output path, its status	The names or details of what was added, removed or changed
How many items were added, removed and changed, and how many errors	The key, which goes only in a header
Its owners, as CODEOWNERS writes them for the diagram and its sources	Anything about the person who pushed

A diagram's status is one of four:

Status	Meaning
In step	The diagram matches its files.
Drifted	The files changed and the diagram did not.
Written	The run wrote the diagram again.
Failed	The run could not make the diagram.

One report holds up to 250 diagrams, and each diagram up to 20 owners. A repository with more diagrams splits its generate settings.

Each run replaces what its repository showed before. A diagram taken out of the repository's settings leaves the dashboard with the next run. The organisation's audit log records that CI sent a report, with the repository and how many diagrams it checked.

3. Read the Drift tab

Open the organisation in the portal and choose the Drift tab. Nothing on it changes anything; only CI writes to it.

Part	What it shows
Totals	Repositories, diagrams, drifted and failed, across every report, before any filter
A repository card	Its name, when it was last checked, and links to its latest run and pull request
A diagram	Its status as a mark and a word, its name and path, its change counts, and its owners
Order	Failed and drifted diagrams first, so a stale one is never below an in-step one

Two filters narrow the list, and the tab says how many diagrams they leave:

Filter	Narrows to
Stale only	Diagrams that drifted or failed
Owner or team	One owner from those the diagrams name, or the diagrams with no owner in CODEOWNERS

Show all clears both. Owners come from the repository's CODEOWNERS, so a team that owns the folder a diagram is written to, or the files it is drawn from, sees its diagrams by choosing its handle.

4. How long runs are kept

The organisation owner's plan decides, and a daily clean-up removes older runs and statuses:

Plan	Drift dashboard	Runs kept
Free	No	Nothing is stored
Pro	Yes	90 days
Enterprise	Yes	365 days, or the days the contract sets

The dashboard goes with the organisation when it is deleted.

5. Plans

The dashboard belongs to the organisation owner's plan, like the organisation's other limits.

The owner's plan	What happens
Free	The Action still checks every diagram and fails the pull request on drift. A report is refused with `plan.drift_dashboard_not_included`, logged as a notice, and nothing is stored. The Drift tab offers the owner the plans and tells everyone else the owner can upgrade.
Pro or Enterprise	Reports are stored and shown.
Moved down to Free	The tab stops showing reports at once, and the next daily clean-up removes what was stored.

Page	Why
Diagrams in CI	The Action's check and its inputs
Enterprise rollout	Reusable workflows, required checks and CODEOWNERS across many repositories
Organisations	Roles, and the organisation keys a report needs
Audit log	The record of each report CI sent
Plans and billing	What Pro and Enterprise include
Privacy policy	What the dashboard stores, and for how long