CI recipes
A GitHub Action, a GitLab CI template and a Vercel Deployment Check, each gating on the baseline and keeping the HTML report.
Three ready-made jobs. Each one pins the CLI, fails only on what a change
introduced once .goflag/baseline.json exists, takes a --max-debt budget, and
keeps the report — goflag-report.json, and goflag-report.html for whoever
reads the pipeline without running goflag. They need goflag 0.2.18 or newer.
CI explains the flags they set; this page is the copy-paste.
GitHub Action
name: seo
on: pull_request
jobs:
goflag:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
- run: corepack enable && pnpm install --frozen-lockfile && pnpm build
- uses: tancredesimonin/goflag/integrations/github-action@v0.2.21
with:
version: 0.2.21
url: http://localhost:3000
start: pnpm start
max-debt: 13The action lives in the goflag repository and is pinned to a release tag, so the
tag and version move together. It sets up Node, runs the CLI, writes a line to
the job summary, and uploads the two reports as the goflag-report artifact,
also when the gate fails — that is when somebody needs to read them.
| Input | Default | What it does |
|---|---|---|
version | required | The @goflag/cli version. A floating one turns another release into your red build |
url | required | What to audit; with start, the local URL |
start | A command that serves the site, passed to --start | |
baseline | .goflag/baseline.json | When the file exists, only new findings fail (--regressions-only) |
max-debt | Fail above this many findings, new or known | |
expect-indexing | no for a preview, yes for production | |
headers | Name: value lines for the audited origin only; values are never printed | |
args | Any other flags, split on spaces | |
report | goflag-report | Base name of the reports and of the artifact |
node-version | 24 | Empty to keep the runner's own Node |
Its output exit-code is goflag's: 0 passed, 1 failed the gate, 2 could
not run.
GitLab CI template
include:
- remote: https://raw.githubusercontent.com/tancredesimonin/goflag/v0.2.21/integrations/gitlab/goflag.gitlab-ci.yml
seo:
extends: .goflag
rules:
- if: $CI_MERGE_REQUEST_IID
variables:
GOFLAG_VERSION: "0.2.21"
GOFLAG_URL: http://localhost:3000
GOFLAG_START: pnpm start
GOFLAG_MAX_DEBT: "13"
before_script:
- corepack enable && pnpm install --frozen-lockfile && pnpm build.goflag is a hidden job: it runs nothing until a job extends it, and your job
decides when and against what. The report is linked from the merge request as
"goflag report". It is served from goflag's public mirror rather than as a
CI/CD component, which needs a public GitLab project.
| Variable | Default | What it does |
|---|---|---|
GOFLAG_VERSION | required | The @goflag/cli version |
GOFLAG_URL | required | What to audit; with GOFLAG_START, the local URL |
GOFLAG_START | A command that serves the site | |
GOFLAG_BASELINE | .goflag/baseline.json | When the file exists, only new findings fail |
GOFLAG_MAX_DEBT | Fail above this many findings, new or known | |
GOFLAG_EXPECT_INDEXING | no for a preview, yes for production | |
GOFLAG_ARGS | Any other flags, split on spaces |
The template's image is node:24-alpine, which has no Chromium: goflag reads
the static HTML and says so. A client-rendered site sets image: to a
Playwright image in its own job — see what about --static.
Vercel Deployment Check
Vercel can hold a production deployment off your production domains until the checks you require have passed. goflag can be one of them: it audits the deployment at its own URL, before a visitor reaches it.
name: goflag
on:
repository_dispatch:
types: [vercel.deployment.ready]
permissions:
contents: read
statuses: write
jobs:
goflag:
if: github.event.client_payload.environment == 'production'
runs-on: ubuntu-latest
steps:
# Pending now, passed or failed when the job ends: the commit status
# Vercel reads. Select this name in Deployment Checks.
- uses: vercel/repository-dispatch/actions/status@v1
with:
name: "Vercel - my-project: goflag"
- uses: actions/checkout@v4
with:
ref: ${{ github.event.client_payload.git.sha }}
- uses: tancredesimonin/goflag/integrations/github-action@v0.2.21
with:
version: 0.2.21
url: ${{ github.event.client_payload.url }}
headers: |
x-vercel-protection-bypass: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}Then, once:
- Require the check. In the Vercel project, Settings › Build and Deployment
› Deployment Checks › Add Checks, choose GitHub and select
Vercel - my-project: goflag. The project has to be linked through Vercel for GitHub, with automatic aliasing for production on. - Let goflag through the protection. Create a Protection Bypass for
Automation secret in Vercel and store it as the repository secret
VERCEL_AUTOMATION_BYPASS_SECRET. goflag sends it to the deployment's origin only and prints its name, never its value.
Three things the setup does not do for you:
- The checkout names the deployed commit. A
repository_dispatchrun starts from the default branch's last commit;client_payload.git.shais the one Vercel built, and the baseline has to be read from it. - Every deployment has its own host. A broken internal link is identified by its absolute target, so one that already existed reads as new on each deployment: fix them before requiring the check.
- Previews are not gated here. Deployment Checks hold production only; this workflow skips the others.
When the check blocks a release you have decided to ship anyway, Vercel's Force Promote, on the deployment's page, goes past it.