Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Guides / GitHub Actions(21 of 37)

GitHub Actions

Set up two-lane visual regression governance in GitHub Actions: a read-only Pull Request check that compares against origin/frontguard-baselines, and an explicit manual workflow for promoting new baselines.

GitHub Actions Two-Lane Baseline Governance
FIG 01 · TWO-LANE CI/CD GOVERNANCE — COMPARISON-ONLY PR WORKFLOW & EXPLICIT BASELINE PROMOTION

Generated workflow

frontguard init --ci generates a comparison-only workflow that invokes the CLI directly, uses contents: read, and uploads the HTML artifact. Configure FRONTGUARD_OPENAI_KEY, FRONTGUARD_ANTHROPIC_KEY, or FRONTGUARD_GEMINI_KEY only if optional analysis is enabled.

The generated workflow fetches origin/frontguard-baselines explicitly. Default actions/checkout fetch-depth: 1 only retrieves the triggering commit, so a CI user who omits that fetch gets an empty expected set.

Complete PR workflow YAML

.github/workflows/frontguard.yml: Lane 1: Comparison-Only PR Gate
name: Frontguard Visual Check
on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout PR branch
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Fetch accepted baselines branch
        run: git fetch origin frontguard-baselines:frontguard-baselines || true

      - name: Setup Node.js 22
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies & Chromium
        run: |
          npm ci
          npx -p @frontguard/cli playwright install --with-deps chromium

      - name: Start application & run Frontguard comparison
        run: |
          npm run build
          npm run start &
          npx wait-on http://localhost:3000 --timeout 60000
          npx -p @frontguard/cli frontguard run --wait-for-stability --redact-sensitive

      - name: Upload HTML Visual Diff Workbench
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: frontguard-report
          path: frontguard-report/

Baseline workflow

Baseline acceptance belongs in a separate explicit workflow: run frontguard update-baselines --confirm-baselines, review the result, then push frontguard-baselines.

.github/workflows/frontguard-update-baselines.yml: Lane 2: Explicit Baseline Promotion
name: Update Frontguard Baselines
on:
  workflow_dispatch:
    inputs:
      reason:
        description: 'Reason for promoting new visual baselines'
        required: true

permissions:
  contents: write

jobs:
  update-baselines:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: git fetch origin frontguard-baselines:frontguard-baselines || true
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: |
          npm ci
          npx -p @frontguard/cli playwright install --with-deps chromium
          npm run build
          npm run start &
          npx wait-on http://localhost:3000 --timeout 60000
          npx -p @frontguard/cli frontguard update-baselines --confirm-baselines
          git push origin frontguard-baselines:frontguard-baselines

Composite Action

The generated workflow and the repository composite Action are separate surfaces. The public Action remains pre-release pending an external consumer smoke test.

Merge queue

Register pull_request and merge_group on the same workflow with an identical job name. GitHub waits for that name before merging the queue.

.github/workflows/frontguard.yml: pull request and merge queue
on: [pull_request, merge_group]

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # smartFilter diffs base...HEAD. fetch-depth: 1 does not contain
          # that base commit. Capture the PR head SHA so the checkout is the
          # pull request head, not an unexpected merge ref.
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.sha || github.event.merge_group.head_sha || github.sha }}

A workflow-level paths: filter on that required check skips the job when the queue commit does not touch those paths, and the queue stays pending. Do not put paths: on a required Frontguard check.

Queue runs compare against the shared latest frontguard-baselines branch until #306. They do not auto-pass. update-baselines on merge_group exits 2 and pushes nothing, even when allow-baseline-writes is true. On merge_group the Action passes --all-routes and sets FRONTGUARD_DIFF_BASE from github.event.merge_group.base_sha when that SHA is present. A queued regression still exits 1 and is written to the job summary, because the payload has no pull request number.