# The drift dashboard

> Page: https://docs.plotwork.dev/drift-dashboard. Index of every page: https://docs.plotwork.dev/llms.txt

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.

## 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](#4-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

1. 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.
2. Store it as a repository or organisation secret named `PLOTWORK_API_KEY`.
3. Add `report-drift: true` to the step that runs `generate`, and pass the key to that step.

```yaml
name: diagrams
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: plotwork-official/plotwork-action@dcec4036897b73bd3ea724b3991f4fd0ac880757 # v1.0.0-beta.14
        with:
          command: generate
          mode: check
          report-drift: true
        env:
          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](https://docs.plotwork.dev/audit-log.md) 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. |

## See also

| Page | Why |
|---|---|
| [Diagrams in CI](https://docs.plotwork.dev/diagrams-in-ci.md) | The Action's check and its inputs |
| [Enterprise rollout](https://docs.plotwork.dev/enterprise-rollout.md) | Reusable workflows, required checks and CODEOWNERS across many repositories |
| [Organisations](https://docs.plotwork.dev/organisations.md) | Roles, and the organisation keys a report needs |
| [Audit log](https://docs.plotwork.dev/audit-log.md) | The record of each report CI sent |
| [Plans and billing](https://docs.plotwork.dev/plans-and-billing.md) | What Pro and Enterprise include |
| [Privacy policy](https://docs.plotwork.dev/privacy-policy.md) | What the dashboard stores, and for how long |