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.
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
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
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.