# Set up the drift check with your agent

> Page: https://docs.plotwork.dev/set-up-ci-with-an-agent. Index of every page: https://docs.plotwork.dev/llms.txt

Hand one request to your coding agent and it draws the repository's diagrams from its own files, adds the GitHub Action that checks them on every pull request, and opens a pull request. The organisation's Drift tab in the portal gives you the request with your organisation in it, ready to copy for your agent.

## TL;DR

| Question | Answer |
|---|---|
| Where do I get the command? | In the portal, open the organisation, then Drift. Choose your agent and press Copy. |
| Which agents? | Claude Code with the Plotwork plugin, Claude Code, Codex, the Cursor CLI, Gemini CLI, and any other agent that can read a web page and edit files. |
| What does the agent do? | It names the sources in `plotwork.config.json`, draws the diagrams with the command line, checks them, writes `.github/workflows/diagrams.yml`, and opens a pull request. |
| Does it see my API key? | No. The agent is told never to ask for a key and never to write one into a file. You set the repository secret yourself. |
| Does anything leave my machine? | The command line draws on your machine and sends nothing. The agent reads this page. Only the Action's report, once the secret is set, reaches Plotwork. |
| What if I do not use an agent? | Follow the steps below yourself, or read [Keep diagrams in sync in CI](https://docs.plotwork.dev/diagrams-in-ci.md). |

## 1. Copy the command

The request is one sentence that points the agent at this page as Markdown. Each agent takes it its own way:

| Agent | Run |
|---|---|
| Claude Code, with the Plotwork plugin | Type `/plotwork:setup-ci acme` in Claude Code. The plugin's skill carries the steps itself. |
| Claude Code, with the Plotwork MCP server | Type `/mcp__plotwork__set-up-drift-check acme`, or pick Set up the drift check from the prompts. |
| Claude Code | `claude "<the request>"` in the repository's folder |
| Codex | `codex "<the request>"` |
| Cursor | `cursor-agent "<the request>"` |
| Gemini CLI | `gemini -i "<the request>"` |
| Any other agent | Paste the request into its chat. |

Replace `acme` with your organisation's address name. The Drift tab fills it in for you. The request holds no double quote, dollar sign or backtick, so it is safe inside the shell's double quotes.

## 2. Set the secret

The check runs on every pull request without a key. To have each run appear on the organisation's Drift tab, the Action needs an organisation key:

1. In the portal, open the organisation, then Keys, and make a key.
2. Set it as the repository secret `PLOTWORK_API_KEY`, with `gh secret set PLOTWORK_API_KEY` (it asks for the value) or in the repository's Settings, Secrets and variables, Actions.

Never paste the key into the agent's chat.

## Steps for an agent

An agent that reads this page follows these steps, in order.

1. **Look before you write.** Find the files Plotwork draws from: Terraform, OpenAPI documents, Compose files, Kubernetes manifests, SQL, Prisma or Drizzle schemas, GitHub Actions workflows and CSV data. Skip installed dependencies, build output and any file that holds secrets, such as `.env`. If `plotwork.config.json` or `.plotwork/config.json` already exists, add to it instead of replacing it.
2. **Name the sources.** Write `plotwork.config.json` at the repository root with `"$schema": "https://docs.plotwork.dev/schemas/plotwork.config.json"`, `"defaults": { "scheme": "auto" }`, and one entry in `sources` for each diagram: `name`, `from` (a path or a glob), `format`, and `out` (`docs/diagrams/<name>.diagram`, or a `diagram` fence of a Markdown page the repository already has, written `docs/architecture.md#<name>`). `npx -y @buun_group/plotwork@0.2.0 import-source --help` lists the formats. Draw one diagram for each stack, service map or schema; three diagrams people read beat a dozen they do not.
3. **Draw them.** Run `npx -y @buun_group/plotwork@0.2.0 generate`. Fix each problem it prints (a code such as S103 names the line of the settings file), then run `npx -y @buun_group/plotwork@0.2.0 generate --check` until it passes. Read the outline of each diagram with `npx -y @buun_group/plotwork@0.2.0 outline <file>` and check it shows what the files say.
4. **Add the check.** Write `.github/workflows/diagrams.yml` as below. Keep the `uses:` line exactly as written: it pins the release by its commit.

   ```yaml
   name: diagrams

   on:
     pull_request:
     push:
       branches: [main]

   permissions:
     contents: read

   jobs:
     drift:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
           with:
             persist-credentials: false
         - uses: plotwork-official/plotwork-action@86ae8278fa771a422d9df60185182f14b8be4db9 # v1.1.0
           with:
             command: generate
             mode: check
             report-drift: true
           env:
             PLOTWORK_API_KEY: ${{ secrets.PLOTWORK_API_KEY }}
   ```

5. **Leave the key to the person.** The report to the organisation's Drift tab needs an organisation API key in the repository secret `PLOTWORK_API_KEY`; the check itself runs without one. Never ask for the key in the chat and never write it into a file. Ask the person to make the key in the Plotwork portal, under the organisation's Keys and CI, and to set the secret themselves, with `gh secret set PLOTWORK_API_KEY` (it asks for the value) or in the repository's Settings, Secrets and variables, Actions. To sign CI in with no key, the organisation can trust the repository instead, under Keys and CI, Trusted publishers (https://docs.plotwork.dev/trusted-publishers); tell the person it exists, and keep the key in the workflow unless they ask for that.
6. **Open a pull request.** Commit the settings file, the diagrams and the workflow on a new branch, and open a pull request titled "Add Plotwork diagrams and the drift check" that lists each diagram and the files it is drawn from. Once it merges and runs with the secret set, the repository appears on the organisation's Drift tab.

## See also

| Page | What it covers |
|---|---|
| [Keep diagrams in sync in CI](https://docs.plotwork.dev/diagrams-in-ci.md) | Every input of the Action, and the workflow that redraws diagrams and opens a pull request |
| [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md) | The `sources` of the settings file, overrides, and generated diagrams |
| [The drift dashboard](https://docs.plotwork.dev/drift-dashboard.md) | What the Drift tab shows once runs report |
| [Claude Code plugin](https://docs.plotwork.dev/agents/claude-code-plugin.md) | Installing the plugin and its skills |