Lighthouse is a lab test. Run it twice on the same URL and the performance score often moves a few points. That is normal: CPU contention, network jitter, and third-party scripts all wobble the result.

If you only glance at PageSpeed Insights before a launch, a regression can ship between glances. A more useful habit is to set a performance budget and let CI fail the deploy when the budget misses.

This post walks through a complete GitHub Actions job that:

  1. Runs real Google Lighthouse on a public URL (mobile and desktop).
  2. Repeats the audit up to three times and reports the median run, so one noisy measurement does not fail the build.
  3. Fails the workflow when the score or Core Web Vitals miss limits you chose.

I will use an Apify Actor I built for the hosted run, and I will say so clearly at the end. The same budget idea works with Lighthouse CI if you prefer to run Chrome yourself on the runner.

What to budget

Google's "good" lab-style thresholds are a reasonable default:

  • LCP (Largest Contentful Paint) ≤ 2500 ms
  • CLS (Cumulative Layout Shift) ≤ 0.1
  • Performance score is a 0–100 weighted blend; a floor such as 90 is stricter than "not poor," so only set it if you can actually hold it

Total Blocking Time (TBT) is the lab stand-in for INP. INP itself needs real user interactions, so do not expect a Lighthouse run to report INP.

Lab data is not Chrome User Experience Report (CrUX) field data. Hardware and network location also differ from PageSpeed Insights, so treat the CI number as a trend on the same setup, not a promise that PSI will show the same score.

Why run Lighthouse off the GitHub runner?

Official Lighthouse CI is the usual path: install Chrome, build the app, run lhci autorun. That is the right default when you can audit localhost or a preview URL the runner can reach.

Sometimes the page you care about is already on a public staging or production URL, and you would rather not install Chrome in the workflow. In that case you can call a hosted Lighthouse run over an API, then fail the job on the run status.

The Actor I use is Lighthouse Audit & Performance Budgets. It runs Lighthouse in Chrome on Apify (no Google API key, no PageSpeed Insights quota), can audit mobile and desktop in the same run, and has a failRunIfBudgetFails flag that marks the Actor run as FAILED when any row misses a budget. Results are still saved. Pages blocked by robots.txt, non-HTML URLs, and failed audits are not charged.

Cost, so there are no surprises

Pricing is pay-per-event (from the public listing):

  • $0.025 per successful Lighthouse run (one URL × one device × one run)
  • $0.001 Actor start fee per GB of memory. The default is 4 GB, so the start fee is $0.004. Keep the default: on Apify, CPU scales with memory, and less CPU can make mobile scores look worse than they are.

Worked example: 1 URL, mobile + desktop, runsPerUrl: 3 → 6 successful audits → $0.15 + $0.004 = $0.154.

If you only need a cheap smoke check, set runsPerUrl: 1 (2 audits → about $0.054). Use 3 when you want a stabler median. Cap the bill with maxTotalChargeUsd.

1. Create an Apify token

  1. Sign in at Apify Console and open Settings → Integrations.
  2. Create an API token with enough rights to start a run and read the default dataset.
  3. In the GitHub repo, add a secret named APIFY_TOKEN. Never put the token in the workflow file.

2. Add a small script the workflow can run

This uses the official apify-client package. actor.call() starts the run and waits until it finishes. waitForFinish on the raw HTTP API only waits up to 60 seconds, which is too short for three mobile + desktop audits, so the client (which polls) is the better fit.

scripts/lighthouse-budget.mjs:

import { ApifyClient } from "apify-client"; const token = process.env.APIFY_TOKEN; const siteUrl = process.env.SITE_URL; if (!token) { console.error("APIFY_TOKEN is missing. Add it as a GitHub Actions secret."); process.exit(1); } if (!siteUrl) { console.error("SITE_URL is missing."); process.exit(1); } const client = new ApifyClient({ token }); const input = { urls: [siteUrl], devices: ["mobile", "desktop"], runsPerUrl: 3, minPerformance: 90, maxLcpMs: 2500, maxCls: "0.1", failRunIfBudgetFails: true, }; // Optional: cap the run so a misconfigured input cannot overspend. const run = await client .actor("rationalistic_tail/lighthouse-budget-auditor") .call(input, { maxTotalChargeUsd: 1 }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); for (const row of items) { const label = `${row.device} ${row.url}`; if (row.status !== "ok") { console.log(`${label}: ${row.status}`); continue; } console.log( `${label}: perf=${row.performance} LCP=${row.lcpMs}ms CLS=${row.cls} budgetPassed=${row.budgetPassed}` ); if (row.budgetFailures?.length) { console.log(" failures:", row.budgetFailures.join("; ")); } if (row.opportunities?.[0]) { const top = row.opportunities[0]; console.log(` top fix: ${top.title} (est. ${top.savingsMs}ms)`); } } if (run.status !== "SUCCEEDED") { console.error(`Actor run ended with status ${run.status}.`); process.exit(1); } const missed = items.filter((row) => row.budgetPassed === false); if (missed.length) { // Belt and braces: should already be a FAILED run when failRunIfBudgetFails is true. process.exit(1); } console.log("All budgets passed."); 

A passing row looks like the public example on the Actor page (numbers will differ on your site):

{ "url": "https://example.com/", "device": "mobile", "status": "ok", "performance": 86, "lcpMs": 2890, "cls": 0.03, "budgetPassed": false, "budgetFailures": ["performance 86 < 90", "LCP 2890ms > 2500ms"], "opportunities": [{ "title": "Eliminate render-blocking resources", "savingsMs": 450 }], "runs": 3, "performanceRange": [84, 89] } 

In that example the run should fail CI: LCP is over 2500 ms and the performance score is under 90, even though CLS is fine.

3. Wire it to GitHub Actions

.github/workflows/lighthouse-budget.yml:

name: Lighthouse budget on: workflow_dispatch: # After your own deploy job, or on a schedule against staging:  # schedule:  # - cron: "0 6 * * 1"  jobs: lighthouse: runs-on: ubuntu-latest timeout-minutes: 20 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: "22" - name: Install apify-client run: npm install apify-client - name: Run Lighthouse budgets env: APIFY_TOKEN: ${{ secrets.APIFY_TOKEN }} # Public staging or production URL. Must be reachable without login.  SITE_URL: ${{ vars.SITE_URL }} run: node scripts/lighthouse-budget.mjs 

Store SITE_URL as a repository variable (Settings → Secrets and variables → Actions → Variables), or hard-code a public staging URL in the workflow if that is simpler.

Run this after the deploy that makes the URL live. Auditing the previous release is how budgets go stale.

Things the audit will not do

  • It honors robots.txt. A disallowed URL is skipped and not charged.
  • It only loads public pages. There is no login, cookie injection, or CAPTCHA solving.
  • It measures lab data in Chrome. Use RUM or CrUX if you need real-user numbers.
  • Lighthouse is pinned on the Actor (currently 12.8.x) and reported on each row as lighthouseVersion.

If you want a first-party, same-commit check against a preview build, use Lighthouse CI instead of, or as well as, a hosted audit of the public URL.

Disclosure

I built the Lighthouse Audit & Performance Budgets Actor that this workflow calls. It is pay-per-event on Apify, as priced above. I also maintain a few related developer tools on the same profile, including a broken-link and #anchor checker and a sitemap extractor / validator / generator. You can call the Lighthouse Actor from an AI agent through Apify's official MCP server if you want the same audit outside CI.

If you already run Lighthouse CI in the repo, you do not need this. If you want a budget gate on a public URL without installing Chrome on the runner, the workflow above is the whole setup.