Setting up Verisual in GitHub Actions

Run npx verisual init in the repository. It creates the Verisual directories and .github/workflows/verisual-visual.yml without overwriting a customized workflow.

The generated workflow establishes the required permissions, Playwright container, Node version, dependency install, and verisual test command. Add your own build, target startup, and readiness steps before the final command.

This npm example tests a local production build. Replace the build, start, health URL, and default branch with the commands your repository actually uses.

name: Verisual visual regression

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  id-token: write
  checks: write

jobs:
  verisual:
    runs-on: ubuntu-latest
    container: mcr.microsoft.com/playwright:v1.61.1-noble
    env:
      VERISUAL_TARGET_URL: http://127.0.0.1:3000
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build
      - name: Start application and wait until ready
        shell: bash
        run: |
          npm run start -- --hostname 0.0.0.0 > /tmp/verisual-app.log 2>&1 &
          for attempt in $(seq 1 120); do
            if curl --fail --silent http://127.0.0.1:3000 > /dev/null; then
              exit 0
            fi
            sleep 1
          done
          cat /tmp/verisual-app.log
          exit 1
      - name: Run Verisual and Playwright
        run: npx verisual test

The job needs these least-privilege permissions:

• contents: read checks out the repository;
• id-token: write lets the CLI request a GitHub OIDC token; and
• checks: write publishes the commit-specific check result.

In Actions, Verisual exchanges the OIDC assertion for a short-lived project token. Do not copy the local CLI credential into GitHub Secrets, and do not create a permanent Verisual CI token.

Pull-request events provide the head commit and target branch used for baseline selection. Pushes to the trusted default branch keep branch state current. Change main in the example if the connected repository uses another default branch.

Verisual verifies live pull-request context before selecting a baseline. If a pull request is retargeted while CI is running, the stale run fails instead of silently comparing against the wrong branch.

On a controlled manual run of the trusted default branch, replace the final command with npx verisual baseline seed. Review the resulting initial candidate in Verisual and approve it before relying on the check for pull requests.

Normal CI should continue to use npx verisual test. Missing baselines and changed checkpoints remain reviewable; the job never approves visual changes automatically.

Set VERISUAL_TARGET_URL to an immutable preview or deployment URL when the application should not run inside the job. Keep the target allowlisted and use a URL that resolves to the exact commit being reviewed.

An approved pull-request candidate is not immediately the active baseline. After the trusted deployment succeeds, runverisual baseline activate with the deployment ID and deployed SHA so Verisual can verify the deployed source before activation.

Use the workflow in this guide when your repository's CI runs the journeys. Your CI starts or reaches the target, runs the CLI, and keeps screenshots that match the baseline inside that job.

If Vercel, Netlify, or Cloudflare Pages already publishes a public GitHub PR preview, you can instead select stored journeys in Project settings. Verisual detects the successful preview signal and runs those journeys in its hosted browser. This option does not need a workflow file in your repository, but it uses hosted runner minutes and compares against the approved default target.

• Confirm the target is ready before the Verisual step begins.
• Confirm the workflow has all three explicit permissions.
• Confirm the repository is linked to the intended Verisual project.
• Use the same pinned container for seeding and comparison runs.
• Do not approve a candidate until its exact commit has been reviewed.