Set up the drift check with your agent

TL;DR

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:

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

   1name: diagrams2
   3on:4  pull_request:5  push:6    branches: [main]7
   8permissions:9  contents: read10
   11jobs:12  drift:13    runs-on: ubuntu-latest14    steps:15      - uses: actions/checkout@v716        with:17          persist-credentials: false18      - uses: plotwork-official/plotwork-action@86ae8278fa771a422d9df60185182f14b8be4db9 # v1.1.019        with:20          command: generate21          mode: check22          report-drift: true23        env:24          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 (opens in a new tab)); 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