Dina's DevOps Blog
Published on

Providing confidence for UI changes: Integrating Storybook and Chromatic into GitHub Actions CI/CD for Visual Feedback

Integrating Storybook into GitHub Actions CI/CD for Visual Feedback

In modern frontend workflows, visual regression and component testing are critical — yet often underutilized — steps in the CI/CD process. That’s where Storybook comes in. When paired with GitHub Actions, it delivers fast visual feedback, boosts confidence in your UI, and helps prevent design bugs from slipping into production.

This guide shows how to integrate Storybook, and optionally Chromatic, into your GitHub CI/CD pipeline for automated builds, live previews, and visual testing.

Why Integrate Storybook in CI/CD?

While Storybook is great for developing and documenting UI components in isolation, plugging it into your CI/CD process unlocks even more power:

  • Visual feedback embedded directly into pull requests
  • Snapshot testing and regression detection
  • Seamless collaboration between developers, designers, and PMs
  • Live previews for every commit

Prerequisites

Before you start, make sure you have:

  • A project with Storybook configured (@storybook/react or similar)
  • GitHub repository with Actions enabled
  • A storybook-static directory generated via npm run build-storybook
  • (Optional, but recommended) A deployment setup like GitHub Pages or Vercel for live previews

Step 1: Build Storybook in GitHub Actions

Create a file at .github/workflows/storybook.yml:

Note: this example uses the main branch, however it is likely you'll want to use a feature branch once everything is configured.

name: Build Storybook

on:
  pull_request:
    branches: [main]

jobs:
  build-storybook:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

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

      - name: Upload Storybook artifact
        uses: actions/upload-artifact@v3
        with:
          name: storybook-static
          path: storybook-static

To make the built Storybook available online, deploy it using GitHub Pages or a service like Vercel.

Example deployment step for GitHub Pages:

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./storybook-static

This publishes your Storybook at a public URL — perfect for async team reviews.

You can enhance pull request visibility by adding a comment with the preview link:

      - name: Comment preview link
        uses: mshick/add-pr-comment@v2
        with:
          message: "📦 Storybook preview: https://myapp.vercel.app/storybook"
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Now anyone reviewing the PR gets instant access to the visual build.

Step 4: Add Chromatic for Visual Regression Testing

Chromatic, built by the creators of Storybook, adds visual testing, UI review workflows, and component history tracking — all without managing your own infrastructure.

Setup Chromatic

Install the CLI npm install --save-dev chromatic

Get your project token from chromatic.com and connect your GitHub repo. Save it as CHROMATIC_PROJECT_TOKEN in your repo's GitHub Secrets.

Then, add a new workflow or update your existing one:

name: Chromatic

on:
  pull_request:
    branches: [main]

jobs:
  chromatic:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Publish to Chromatic
        run: npx chromatic --project-token=${{ secrets.CHROMATIC_PROJECT_TOKEN }}

What you get, as an Organization

  • Pixel-perfect visual comparisons
  • A hosted interface for reviewing UI changes
  • PR comments with side-by-side diffs
  • Approval flows for design and product stakeholders

From the business perspective:

  • Confidence in every UI update
  • Faster feedback and fewer surprises
  • Automated visual regression testing
  • Smoother collaboration across teams

What's Next?

  • Add Lighthouse CI for performance audits
  • Use @storybook/test-runner for functional testing
  • Publish Storybook docs as part of your component library