How to Update the Chromatic CLI in a GitHub Actions Workflow

If your workflow uses Chromatic’s GitHub Action, update the version tag on its uses line. Choose chromaui/action@latest to follow all updates, chromaui/action@vX to stay on a major version line, or chromaui/action@vX.Y.Z to pin a specific release. The action typically auto-upgrades the Chromatic CLI. If your workflow runs npx chromatic directly, install Chromatic as a development dependency to manage its version through your package manifest and lockfile. See Chromatic’s GitHub Actions documentation and CLI documentation.

Update the GitHub Action version

Open the workflow file that runs Chromatic, usually under .github/workflows/.
Find the step whose uses value starts with chromaui/action@.
Replace the tag with your chosen update policy: latest, a major tag such as vX, or a full version such as vX.Y.Z.
Commit the workflow change and run the workflow. Check the Chromatic step’s logs and the resulting build in Chromatic.

For example, replace the placeholders below with the major version or full version you intend to use:

name: Chromatic

on:
  push:
    branches: [main]

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Run Chromatic
        uses: chromaui/action@vX
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

This is a workflow pattern: retain the Node version and dependency-install command that match your repository. The important update is the action tag. Chromatic’s setup guidance includes a full checkout, Node setup, dependency installation, and a project token stored as a repository secret. Never commit the token value in the YAML file. If the workflow already uses chromaui/action@latest, the action tag already follows all new updates; change it only if you want a different update policy.

Choose how Chromatic updates

Tag pattern	Update behavior	Use it when
`@latest`	Follows all new updates.	You want the action to pick up new releases automatically.
`@vX`	Receives features and fixes within a chosen major version, avoiding breaking changes from a new major version.	You want updates within a major line while controlling major-version changes.
`@vX.Y.Z`	Stays on the specified version until you edit the workflow tag.	You need a fixed version and explicit version-change reviews.

Use the real version tag you have selected in place of the placeholders. Chromatic’s documentation uses v10 and v10.0.0 to illustrate tag formats; those examples are not a recommendation for the newest release. A pinned tag gives predictable inputs to CI, but add a regular review of the tag so a deliberate pin does not become an unnoticed old version.

If the workflow runs the CLI directly

A workflow may call npx chromatic rather than use chromaui/action. If the project does not have Chromatic installed, npx downloads and runs the latest CLI. To make the CLI version follow the project manifest and lockfile, add it as a development dependency with the package manager the project already uses.

npm

npm install chromatic --save-dev
npx chromatic --project-token="$CHROMATIC_PROJECT_TOKEN"

Yarn

yarn add --dev chromatic
yarn chromatic --project-token="$CHROMATIC_PROJECT_TOKEN"

pnpm

pnpm add --save-dev chromatic
pnpm exec chromatic --project-token="$CHROMATIC_PROJECT_TOKEN"

Commit the updated dependency manifest and lockfile. In GitHub Actions, use the matching reproducible install command, such as npm ci for npm, before invoking the CLI. Store CHROMATIC_PROJECT_TOKEN as a GitHub Actions repository secret and expose it to the step or reference it as shown in the command. Do not put the token directly in a committed workflow file.

Chromatic recommends installing the package when pairing the CLI with Vitest, Playwright, or Cypress so it stays in sync with the related Chromatic test package. This is a recommendation for those integrations, not a requirement for every basic Storybook workflow. Read the Chromatic CLI guide for supported CLI options.

Keep the rest of the workflow intact

Checkout history: Chromatic’s GitHub Actions example checks out the repository with fetch-depth: 0. Preserve this when updating the action tag.
Node and dependencies: Keep the Node version and package-manager install process aligned with the project and its lockfile.
Project token: Use a repository secret and reference it as ${{ secrets.CHROMATIC_PROJECT_TOKEN }}. Do not paste the secret into YAML or logs.
Trigger: Chromatic recommends running the step on push. Its documentation notes that a pull_request trigger can, in some circumstances, lead to lost baselines or an unexpected baseline from main. Treat trigger changes separately from version updates.

See Chromatic’s GitHub Actions setup and CI documentation for configuration details.

Verify the update

Inspect the diff and confirm only the intended action tag or dependency and lockfile entries changed.
Run the workflow on a push to the branch configured for Chromatic.
Confirm dependency installation succeeds, the Chromatic step receives the project token, and the step completes successfully.
Review the new build in Chromatic. If the CLI is invoked directly, check the workflow logs to confirm the command is using the installed project dependency.

A successful workflow run verifies that the selected action or CLI can run with the current workflow setup. It does not by itself prove that every visual baseline or test integration behaves as intended; review the resulting build and any project-specific checks.

Troubleshooting

Symptom	Likely cause	What to check
Chromatic runs a different version policy than expected	The action tag still points to `@latest`, a major tag, or a full version you did not intend.	Check the exact `uses: chromaui/action@...` value in the workflow that actually ran. For direct CLI use, check whether Chromatic is installed and locked as a project dependency.
The CLI changes unexpectedly between workflow runs	The workflow runs `npx chromatic` without a project dependency, so npx downloads the latest CLI.	Install Chromatic as a development dependency, commit the manifest and lockfile, and use the repository’s lockfile-based install command.
The Chromatic step cannot authenticate	The repository secret is missing, named differently, unavailable to the event context, or not passed to the step.	Confirm `CHROMATIC_PROJECT_TOKEN` exists in repository secrets and the workflow references the exact secret name. Do not print the secret while debugging.
The step cannot find the expected project files or build	The workflow’s checkout, install, or build setup differs from the project’s requirements.	Check that checkout and dependency installation happen before Chromatic, preserve the full history setting from Chromatic’s example, and retain any project build steps required by the existing workflow.
Visual changes appear against an unexpected baseline	The trigger or branch context may be selecting a different baseline. Chromatic notes that pull request runs can cause unexpected baseline behavior in some cases.	Review the event and branch configuration separately from the version change. Consider the documented push trigger guidance and inspect the affected build’s baseline.
A pinned workflow stays on an old CLI release	A full version tag does not move automatically.	Review the pinned version periodically and update the tag deliberately when you choose to adopt another release.

Performance, reliability, and maintenance

The version tag determines how changes enter CI; it does not establish a runtime or performance guarantee. A full version pin limits version drift between runs, while @latest can adopt new changes without a workflow edit. A major tag sits between those policies by following changes within that major line. Choose according to how your team reviews CI changes, and keep the checkout, Node, package-manager, and secret configuration stable while updating the version.

For direct CLI workflows, dependency management makes the selected package version part of the project’s normal dependency update process. Keep the lockfile committed and use its matching install mode in CI. For integrations with Vitest, Playwright, or Cypress, follow Chromatic’s recommendation to install the package so the CLI and test package can remain in sync.

Or skip the browser setup

If this workflow work is part of capturing a website for documentation, debugging, or review, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One GET request returns a PNG, JPEG, WebP, or PDF, without setting up a browser in your own workflow. See the ScreenshotNeo API documentation.

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

Python: requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90). Node.js: const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);. Replace the example URL and save or process the response body as needed; consult the docs for response and capture options.

Cookie banners are accepted and removed before capture; 60+ known consent platforms, newsletter popups, and chat widgets can be removed, and each step can be turned off.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses include X-Page-Verdict and X-Billed headers.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots.

FAQ

Does changing the GitHub Action tag update Chromatic’s CLI?

Yes. Chromatic says the GitHub Action typically auto-upgrades the CLI; the action tag selects the update policy.

How do I pin Chromatic in GitHub Actions?

Use a full version tag such as chromaui/action@vX.Y.Z. For direct CLI use, install Chromatic as a development dependency and commit the lockfile.

Should I use `@latest` or a pinned version?

Use @latest to follow all updates, a major tag to follow updates within that major version, or a full version tag to require a workflow edit before changing versions.

Do I need to change the workflow trigger when updating the version?

No. The action tag and trigger are separate workflow choices. Chromatic recommends a push trigger for its step and documents possible baseline issues with pull request triggers in some circumstances.