Gate CI with Lighthouse
A performance gate only works if it runs on every change, on a stable profile, with assertions tight enough to fail. That is Lighthouse CI, configured, not a dashboard nobody opens.
Procedure
Install and configure assertions in lighthouserc.json, averaging three runs to damp variance:
{"ci":{"collect":{"numberOfRuns":3,"url":["https://pr-123.staging.shop.example.com/"],
"settings":{"preset":"perf","form-factor":"mobile"}},
"assert":{"preset":"lighthouse:recommended",
"assertions":{"largest-contentful-paint":["error",{"maxNumericValue":2500}]}},
"upload":{"target":"temporary-public-storage"}}}
Run it locally against the preview URL before pushing the workflow:
npx @lhci/cli autorun --config=lighthouserc.json
In CI, wait for the preview deploy to be ready, then run against that URL, not production.
Fail the job on error-level assertions; keep informational ones at warn so the check stays meaningful.
Upload results so the next PR can be compared against the branch baseline, not just absolute thresholds.
Re-baseline deliberately when a real design change moves the numbers, and say so in the PR.
Pitfalls
- Running against production URLs, which change under you and make the check flaky and unreviewable.
- Asserting on the composite performance score, which swings with unrelated audits and blocks unrelated PRs.
- A single run per URL, where a 10-15% jitter turns the gate into coin flips.
- Never re-baselining, so a gate that once failed for a real reason is disabled to unblock a release.
- Testing the staging build with debug bundles, which measures a configuration no user ever sees.
Verification
npx @lhci/cli autorun --config=lighthouserc.json; echo "exit=$?"
A non-zero exit means at least one assertion failed. Report the URL tested, the run count, and which assertion gated the build.
1---2name: gate-ci-with-lighthouse3description: Use when regressions reach production unnoticed. Runs Lighthouse CI per pull request with assertions and a server for trend history.4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/gate-ci-with-lighthouse6---78# Gate CI with Lighthouse910A performance gate only works if it runs on every change, on a stable profile, with assertions tight enough to fail. That is Lighthouse CI, configured, not a dashboard nobody opens.1112## Procedure13141. Install and configure assertions in `lighthouserc.json`, averaging three runs to damp variance:1516 {"ci":{"collect":{"numberOfRuns":3,"url":["https://pr-123.staging.shop.example.com/"],17 "settings":{"preset":"perf","form-factor":"mobile"}},18 "assert":{"preset":"lighthouse:recommended",19 "assertions":{"largest-contentful-paint":["error",{"maxNumericValue":2500}]}},20 "upload":{"target":"temporary-public-storage"}}}21222. Run it locally against the preview URL before pushing the workflow:2324 npx @lhci/cli autorun --config=lighthouserc.json25263. In CI, wait for the preview deploy to be ready, then run against that URL, not production.274. Fail the job on `error`-level assertions; keep informational ones at `warn` so the check stays meaningful.285. Upload results so the next PR can be compared against the branch baseline, not just absolute thresholds.296. Re-baseline deliberately when a real design change moves the numbers, and say so in the PR.3031## Pitfalls3233- Running against production URLs, which change under you and make the check flaky and unreviewable.34- Asserting on the composite performance score, which swings with unrelated audits and blocks unrelated PRs.35- A single run per URL, where a 10-15% jitter turns the gate into coin flips.36- Never re-baselining, so a gate that once failed for a real reason is disabled to unblock a release.37- Testing the staging build with debug bundles, which measures a configuration no user ever sees.3839## Verification4041 npx @lhci/cli autorun --config=lighthouserc.json; echo "exit=$?"4243A non-zero exit means at least one assertion failed. Report the URL tested, the run count, and which assertion gated the build.