Run Frontguard visual regression tests in GitHub Actions with the official action.

GitHub Actions

Frontguard provides an official GitHub Action for visual regression testing in your CI pipeline.

Quick Setup

.github/workflows/visual-regression.yml

name: Visual Regression Tests
on:
  pull_request:
    branches: [main]

jobs:
  visual-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy Preview
        # Your deployment step here — Vercel, Netlify, etc.
        # Frontguard auto-detects the preview URL

      - name: Run Frontguard
        uses: ravidsrk/frontguard@main
        with:
          url: ${{ env.PREVIEW_URL }}  # Or let it auto-detect
        env:
          FRONTGUARD_OPENAI_KEY: ${{ secrets.FRONTGUARD_OPENAI_KEY }}

Action Inputs

Input	Required	Default	Description
`url`	No	Auto-detected	Base URL to test
`routes`	No	Auto-discovered	Comma-separated routes
`viewports`	No	`375,768,1440`	Comma-separated viewport widths
`browsers`	No	`chromium`	Comma-separated browsers
`threshold`	No	`0.1`	Pixel diff threshold percentage
`config`	No	Auto-detected	Path to `frontguard.config.ts`
`ai-provider`	No	—	AI provider: `openai` or `anthropic`
`ai-model`	No	—	AI model name
`update-baselines`	No	`false`	Accept current as new baselines
`github-token`	No	`github.token`	Token for PR comments

Action Outputs

Output	Description
`result`	Full JSON result of the test run
`regressions`	Number of regressions found
`status`	`pass`, `fail`, or `error`

Complete Example

Here's a full workflow with Vercel preview deployments:

.github/workflows/visual-regression.yml

name: Visual Regression Tests

on:
  pull_request:
    branches: [main]
  deployment_status:

jobs:
  visual-test:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request' || github.event.deployment_status.state == 'success'
    steps:
      - uses: actions/checkout@v4

      - name: Run Frontguard
        id: frontguard
        uses: ravidsrk/frontguard@main
        with:
          viewports: '375,768,1440'
          browsers: 'chromium'
          threshold: '0.1'
          ai-provider: 'openai'
          ai-model: 'gpt-4o'
        env:
          FRONTGUARD_OPENAI_KEY: ${{ secrets.FRONTGUARD_OPENAI_KEY }}

      - name: Check Results
        if: always()
        run: |
          echo "Status: ${{ steps.frontguard.outputs.status }}"
          echo "Regressions: ${{ steps.frontguard.outputs.regressions }}"

What the Action Does

The action runs these steps automatically:

Setup Node.js — Installs Node.js 20
Install Frontguard — npm install -g frontguard@latest
Install Browsers — npx playwright install --with-deps <browsers>
Detect Preview URL — Checks environment variables from Vercel, Netlify, Cloudflare, Railway, Render
Run Frontguard — Executes the full pipeline with your configuration
Upload Report — Uploads the HTML report as a build artifact

Using with Preview Deployments

Vercel

- name: Wait for Vercel Preview
  uses: patrickedqvist/wait-for-vercel-preview@v1.3.2
  id: preview
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    max_timeout: 300

- name: Run Frontguard
  uses: ravidsrk/frontguard@main
  with:
    url: ${{ steps.preview.outputs.url }}

Netlify

Frontguard auto-detects DEPLOY_PRIME_URL set by Netlify's CI environment:

- name: Run Frontguard
  uses: ravidsrk/frontguard@main
  # URL auto-detected from DEPLOY_PRIME_URL

Updating Baselines in CI

Create a separate workflow or trigger for baseline updates:

.github/workflows/update-baselines.yml

name: Update Visual Baselines

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Update Baselines
        uses: ravidsrk/frontguard@main
        with:
          url: 'https://your-production-url.com'
          update-baselines: 'true'

Secrets Configuration

Add these secrets to your repository settings (Settings → Secrets and variables → Actions):

Secret	Required	Description
`FRONTGUARD_OPENAI_KEY`	For AI analysis	OpenAI API key
`FRONTGUARD_ANTHROPIC_KEY`	For AI analysis	Anthropic API key (alternative)

GITHUB_TOKEN is provided automatically by GitHub Actions. You don't need to create it as a secret.

Downloading Reports

The HTML report is uploaded as a build artifact on every run. Download it from the Actions tab:

Go to your repository → Actions tab
Click on the workflow run
Under Artifacts, download frontguard-report
Open index.html for an interactive visual diff viewer

GitHub Actions

On this page