How to Run Chromatic (Storybook Visual Tests) in CI

Chromatic builds and snapshots your Storybook in its cloud. CI failures come down to a missing project token, a shallow git checkout, or forked-PR secret access.

Chromatic publishes your Storybook to its service and runs visual diffs there, so you do not need browsers on the runner. The CI work is providing the project token and a full git history (Chromatic uses git ancestry to find baselines) - and handling forks that cannot read the token.

Why it fails in CI

Without CHROMATIC_PROJECT_TOKEN, Chromatic cannot authenticate. With GitHub’s default shallow checkout (fetch-depth: 1), Chromatic cannot walk git history to find the baseline and warns or rebaselines incorrectly. Forked PRs have no secret access, so the token is empty.

Install & run it reliably

Check out full history, build Storybook (or let Chromatic build it), and run Chromatic with the project token. Use the official action or the CLI.

.github/workflows/chromatic.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0          # full history for baseline detection
- run: npm ci
- uses: chromaui/action@latest
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
    # buildScriptName: build-storybook

Cache & speed

Chromatic runs the browser work in its cloud, so there is no browser binary to cache - cache node_modules/~/.npm and the Storybook build instead. Use TurboSnap (only snapshot changed stories) to cut snapshot counts, and ensure fetch-depth: 0 so incremental baselines work.

Common errors

Missing project token → set CHROMATIC_PROJECT_TOKEN from secrets.
Chromatic only has a shallow git history → set fetch-depth: 0 in checkout.
No baseline / everything flagged as new → shallow checkout or first run; full history fixes ongoing builds.
Forked PR has no token → gate Chromatic to same-repo runs or accept skipped runs on forks.

Key takeaways

Provide CHROMATIC_PROJECT_TOKEN and check out full history (fetch-depth: 0).
Chromatic snapshots in its cloud - no browser binaries to install or cache.
Use TurboSnap to reduce snapshots; forks cannot read the token.