How to Set Up Chromatic with Storybook and GitHub Actions

To run Chromatic visual tests in GitHub Actions, connect your Storybook project to Chromatic, save the Chromatic project token as a GitHub Actions secret, and add a workflow that installs dependencies and invokes chromaui/action. The action builds or uses your Storybook, uploads it for visual testing, and reports results for review. Keep the token out of source code and align the workflow’s Node version, action version, and install command with your repository and the current official documentation.

1. Check your Storybook version and project setup

First check the Storybook version in your package manifest or lockfile, and identify your package manager. The official @chromatic-com/storybook addon supports Storybook 7.6 or higher according to Storybook’s visual testing guide. Chromatic’s CLI and GitHub Action integration listing separately describes support for Storybook 6.5 and higher; these version thresholds apply to different integration paths, so verify the docs for your chosen path and installed version.

If you use the addon, its documented installation command is:

npx storybook@latest add @chromatic-com/storybook

Check the documentation that matches your Storybook version before running a latest-version installer in an older project. The addon supports local visual test interaction; you can also configure GitHub Actions to run Chromatic directly without using the addon panel locally.

2. Connect the project and configure the addon

Follow the addon setup to select or create a Chromatic project and connect its configuration to Storybook. The guide documents these optional settings in chromatic.config.json:

projectId: the Chromatic project identifier.
buildScriptName: the package script used to build Storybook.
debug: enables debugging output.
zip: packages the build as a zip; the guide recommends it for large projects.

Use the values generated or specified by your project setup. Do not confuse the project identifier with the project token used to authenticate CI.

3. Store the project token in GitHub

Create a repository secret named CHROMATIC_PROJECT_TOKEN in GitHub’s repository settings. Paste the token from the Chromatic project setup into that secret. The workflow will reference it as ${{ secrets.CHROMATIC_PROJECT_TOKEN }}; do not put the token in a committed YAML file, package script, or log output.

Chromatic’s publishing example also uses GITHUB_TOKEN for git-provider integration. Follow the permissions and inputs required by the specific action version you choose; do not assume that the project token and GitHub token serve the same purpose.

4. Add a GitHub Actions workflow

Create .github/workflows/chromatic.yml. This example follows the structure in Chromatic’s current GitHub Actions guide. The action tag and Node runtime shown are examples from that guide; confirm supported versions before adopting them. Change npm ci if your project uses another package manager, and commit the matching lockfile.

name: Chromatic

on: push

jobs:
  chromatic:
    name: Run Chromatic
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v7
        with:
          node-version: 24.20.0
      - name: Install dependencies
        run: npm ci
      - name: Run Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

For a project that uses another package manager, install dependencies with its lockfile-respecting CI command. For example, use the appropriate frozen or immutable install mode for pnpm or Yarn. Keep the package manager version consistent with the repository configuration.

The example runs on pushes. To have results available for pull request review, ensure the workflow is triggered for the branches and pull requests your team uses, and follow Chromatic’s current guidance for the selected event and action version. You can add a pull request trigger if needed, while accounting for fork secret restrictions and your repository’s security policy.

Use a prebuilt Storybook directory

If an earlier workflow step builds Storybook, pass the resulting directory to the Chromatic action with storybookBuildDir. The path must match the actual output directory produced by your build command.

- name: Build Storybook
  run: npm run build-storybook

- name: Run Chromatic
  uses: chromaui/action@latest
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
    storybookBuildDir: storybook-static

Use this pattern when your workflow needs to build once and reuse that output. Otherwise, follow the action’s documented build flow and avoid adding a separate build step without a reason.

5. Review visual changes and baselines

Chromatic captures rendered stories and compares them with prior baselines. When a visual difference appears, inspect it in the Visual Tests panel: correct unintended changes in the component or its environment, and accept a change only when it is intentional. Storybook’s guide says that baselines accepted through its addon are auto-accepted in CI, so the same baseline change does not need a second review.

Once configured, the documentation describes a UI Tests check on pull or merge requests. If your team wants this check to gate merging, configure it as a required check in your git provider according to your repository’s merge policy.

6. Choose between Chromatic and the Storybook test runner

Need	Chromatic	Storybook test runner
Primary role	Hosted visual and component checks with review workflows	Configurable story testing for broader custom checks
Where it runs	Chromatic cloud, commonly triggered from CI	Locally or in CI
Review output	Visual differences, baselines, and git-provider integration	Test output and configurable workflows
Can be combined?	Yes; use for visual review	Yes; use for custom tests alongside Chromatic

These tools overlap, but they are not identical. Storybook documents using its test runner locally and Chromatic in CI, or using Chromatic for visual and component testing while the runner covers custom checks. Exact features depend on versions and configuration.

7. Troubleshooting

Symptom	Likely cause	What to check
Authentication fails or the action cannot find the project	The secret is missing, misspelled, unavailable to the event, or contains the wrong token.	Confirm the repository secret is named `CHROMATIC_PROJECT_TOKEN`, the YAML references that exact name, and the token belongs to the intended Chromatic project. Forked pull requests may not receive repository secrets; use an event and workflow design that respects GitHub’s secret-access rules.
Chromatic cannot find the Storybook build	The output directory is wrong, or a prebuild step did not run.	Check the build command’s output and set `storybookBuildDir` to that directory. Ensure the build step succeeds before invoking the action.
Dependency installation fails in CI	The workflow uses the wrong package manager or the lockfile is out of sync.	Use the repository’s package manager and its CI install mode, and commit the lockfile. Check the Node version required by the project and action.
Stories differ between local and CI runs	The environments may differ in dependencies, runtime, fonts, assets, environment variables, or build configuration.	Compare the Node and package manager versions, ensure required assets and environment variables are available, and reproduce the CI build locally. Do not accept a baseline until you understand the difference.
The addon command or configuration does not match the project	The project may use an older Storybook version than the documentation or installer expects.	Check the version-specific Storybook and Chromatic documentation. The addon threshold and the separate CLI/action compatibility listing describe different paths.
The workflow runs but does not report the result where expected	The workflow event or git-provider integration may not match the desired pull request check.	Review the workflow triggers, action inputs, token availability, and the current Chromatic instructions for pull request integration. Confirm the check appears before making it a required merge check.

8. Performance, reliability, and cost considerations

Build once when useful: pass storybookBuildDir when a preceding step already produced the build and your pipeline should reuse it.
Use a full checkout when required: Chromatic’s current workflow example sets fetch-depth: 0. Preserve the documented checkout setup unless the current action guidance says otherwise.
Keep environments repeatable: pin the project’s runtime and use its committed lockfile so changes in dependency resolution do not create confusing visual results.
Protect credentials: keep project tokens in GitHub secrets and account for events, such as pull requests from forks, that cannot access secrets.
Review before accepting: baseline acceptance changes what future comparisons treat as expected. Investigate unexpected diffs before updating baselines.
Check current plan terms directly: the supplied setup documentation does not establish Chromatic pricing or plan limits, so this guide makes no cost estimate.

Or skip the browser setup

If your task is to capture a page screenshot rather than run Storybook component visual tests, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. See the API documentation for parameters.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. These are website captures, not a replacement for Chromatic’s Storybook visual testing workflow. Sign up for 1,000 free screenshots a month, no card required.

FAQ

How do I add Chromatic to GitHub Actions?

Add a workflow that checks out the project, installs dependencies, and invokes chromaui/action with the project token from a GitHub secret. Confirm the action and runtime versions against the current Chromatic guide.

How do I store the Chromatic project token?

Add it as a GitHub repository secret named CHROMATIC_PROJECT_TOKEN and reference it through ${{ secrets.CHROMATIC_PROJECT_TOKEN }} in the action input.

Do I need the Storybook addon to run the GitHub Action?

The addon enables local visual testing interaction. Chromatic also documents direct GitHub Actions setup, so choose the integration path that fits your workflow and Storybook version.

Should I accept every visual difference?

No. Accept a difference as a new baseline only after confirming the rendered change is intentional.