Visualise changes on every PR

What you need to set this up

• A published design system in your workspace. The PR-review action renders against an existing DS; it doesn't create one. See Keep components in sync.
• The Statecraft GitHub App installed on the account or org that owns the repo (Account → GitHub access → Install GitHub App), with this repo in the selected list. Without it, the worker can't clone the PR's head commit and runs fail with "GitHub repository not found".
• A workspace API token with the pr-review:run scope.

1. Mint a workspace API token

From the editor: Workspace Settings → API tokens → Create token, check the pr-review:run scope, copy the sck_… value.

Or from the CLI:

statecraft tokens create \
  --workspace <your-workspace-slug> \
  --name pr-review-ci \
  --scope pr-review:run

Save the resulting sck_… value as a GitHub repo secret. The conventional name is STATECRAFT_PR_REVIEW_TOKEN — the workflow below references that.

2. Add slug: to your statecraft.yaml

The PR-review action reads the design-system slug from the top of your repo's statecraft.yaml — the same file you use for CI publishing. Add a top-level slug: line if it isn't already there:

slug: my-design-system

source:
  live: true

build:
  framework: react
  entry: src/components/index.ts

# … the rest of your manifest

Prefer to keep the slug out of the manifest? Pass design-system: explicitly in the workflow's with: block. The workflow input takes precedence over the YAML.

3. Add the workflow

Place at .github/workflows/pr-review.yml:

name: Statecraft PR review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      pull-requests: write   # for the sticky comment
      contents: read
    steps:
      - uses: statecraftapp/pr-review-action@v2
        with:
          statecraft-token: ${{ secrets.STATECRAFT_PR_REVIEW_TOKEN }}
          # Optional: narrow what the survey agent considers.
          # scope: "checkout flow"
          # Optional: override toolchain detection if heuristics misfire.
          # node-version: "20"
          # package-manager: pnpm

Open a PR

Push a branch, open a PR. The workflow runs; you'll see a check-mark land on the PR with status updates. Within 30–120 seconds (typical) for a single-journey PR, the sticky comment appears. Push more commits and the comment updates in place.

Narrowing what the agent considers

On big PRs that touch many areas of the codebase, you can give the survey agent a free-text scope hint so it doesn't propose previews for journeys you don't care about right now. Pass scope: in the workflow's with: block:

with:
  statecraft-token: ${{ secrets.STATECRAFT_PR_REVIEW_TOKEN }}
  scope: "checkout flow only"

Free text — phrase it however reads naturally. Useful on monorepos where one PR can intersect a dozen journeys.

v2 vs v1: where the build runs

Starting with @v2 (the default since 2026-05-23), the action installs Node + pnpm/npm/yarn on the GitHub Actions runner using your repo's own version pins (.nvmrc, package.json#packageManager, lockfile), then runs statecraft publish for the PR's ephemeral DS bundle inline. The same toolchain that powers your canonical CI publish powers PR-review's per-PR build — no more "works in my CI, breaks in Statecraft's" surprises. PRs that don't touch DS source skip the build entirely. @v1 keeps the older server-side build path and continues to work through at least 2026-08, but new setups should use @v2.

Cancelling a run

Clicking Cancel on the workflow run in the GitHub Actions UI propagates back to Statecraft — the worker exits cleanly and cascades the cancel to any render runs it had already spawned. No orphaned previews left running, no agent credits burned past the cancel point.

Troubleshooting

"Design system slug is required." The action couldn't find a top-level slug: in your statecraft.yaml and no design-system: input was passed. Add one or the other.

"Design system with slug … not found in this workspace." The slug resolved fine — it just doesn't match a design system in the workspace your sck_… token belongs to. Common when you've been working in one workspace and the token is scoped to another. Run statecraft design-system ls to see what exists where, then either align the YAML slug:, pass design-system: in the workflow's with: block, or import the DS into the right workspace.

"GitHub repository not found." Usually means the Statecraft GitHub App isn't installed on the repo's account or organization — or the install exists but doesn't include this specific repo. The user behind the workspace token (whoever minted sck_…) installs the App from Account → GitHub access → Install GitHub App, picking the right org and including this repo in the selection. For org installs the org's admin may need to approve the request before the App becomes active.

"Agent credit limit reached." Your account hit its per-period agent-credit ceiling and the run was refused (HTTP 402) before any agents spawned. Either upgrade your plan or add your own Anthropic API key on the Account page — BYO-key bypasses the metering and you pay Anthropic directly. See Billing.

The workflow times out / hangs in "spawning". Each queued run gets its own ephemeral worker spawned on demand, so simultaneous PRs don't queue against a shared budget. If a run still hangs, check the workspace's PR Reviews surface for the run's currentPhase and inspect the worker logs linked from there.