# Setup a Chromatic workflow

# Create the workflow file

To set up a GitHub Actions Chromatic workflow for a project, first, create a chromatic.yml file inside the .github/workflows folder at the root of the solution's workspace:

.github/workflows/chromatic.yml
workspace
├── .github
├──── workflows
├────── chromatic.yml
├── package.json

Then, open the newly created file and copy/paste the following content:

.github/workflows/chromatic.yml
name: Chromatic

# PNPM setup based on https://github.com/pnpm/action-setup#use-cache-to-reduce-installation-time.

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
    types:
      - opened
      # To conditionally execute the workflow based on a PR label.
      - labeled
  workflow_dispatch:

env:
  CI: true

concurrency:
  group: chromatic-${{ github.ref }}
  cancel-in-progress: true

jobs:
  chromatic:
    runs-on: ubuntu-latest

    permissions:
      pull-requests: write
    
    steps:
      - name: Early exit if "run chromatic" label is not present
        if: github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'run chromatic')
        run: |
          echo "No \"run chromatic\" label present. Skipping Chromatic workflow."
          # exit as neutral.
          exit 78

      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0
          # Refer to: https://www.chromatic.com/docs/github-actions/#recommended-configuration-for-build-events.
          ref: ${{ github.event.pull_request.head.ref }}
        env:
          # Refer to: https://www.chromatic.com/docs/github-actions/#recommended-configuration-for-build-events.
          CHROMATIC_BRANCH: ${{ github.event.pull_request.head.ref || github.ref_name }}
          CHROMATIC_SHA: ${{ github.event.pull_request.head.sha || github.ref }}
          CHROMATIC_SLUG: ${{ github.repository }}

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          run_install: false

      - name: Install Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '>=24.0.0'
          check-latest: true
          cache: pnpm
          cache-dependency-path: pnpm-lock.yaml

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          onlyChanged: true
          exitOnceUploaded: true
          autoAcceptChanges: main

      - name: Remove "run chromatic" label after Chromatic completion
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v8
        with:
          script: |
            github.rest.issues.removeLabel({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                name: 'run chromatic'
            });

# Create a label

Next, since the workflow runs only when the run chromatic label is present on the pull request. Refer to the GitHub documentation to create a label named run chromatic.

# Add a required status check

Finally, because the workflow only runs when the run chromatic label is present on the pull request, it is important to make the Chromatic workflow a required status check. This ensures reviewers are reminded to run Chromatic before merging.

To do so, add a required status check for the chromatic job on the default branch ruleset:

When adding a required status check, search for the job name, not the workflow name.

# Renovate bot and Changesets

If the repository uses Renovate bot or Changesets automation tools, consider excluding the branches they create from the default branch ruleset:

# Try it 🚀

To test your new CI workflow:

Create a pull request in GitHub and confirm that the Chromatic workflow fails.
Add a run chromatic label to the PR.
Confirm that the Chromatic workflow runs successfully.