Lighthouse CI can report green on a pull request while the client’s monthly PageSpeed pack still shows amber on Largest Contentful Paint. Both results can be “correct.” They measured different URLs, different strategies, or different thresholds that nobody reconciled when the retainer started. That mismatch is expensive: engineering trusts the gate, sponsors distrust the report, and the agency spends the call explaining why two greens disagree.
Web performance budgets only work when the merge gate and the client review speak the same language. What follows is the agency ritual that keeps those numbers aligned: pick thresholds once, wire them into CI for protection, and reuse them on production schedules for the retainer. For the CI plumbing itself, use How to Set Up Performance Budgets in CI/CD Pipelines. For a reusable threshold sheet, use Performance Budget Thresholds Template.
Why CI budgets and client budgets drift apart
Teams usually invent two documents by accident. Engineering owns a Lighthouse CI assertion file tuned to preview URLs. Account leads own a slide that still says “keep PageSpeed healthy” without naming LCP, Interaction to Next Paint, or Cumulative Layout Shift. After a few sprints the CI file tightens, the deck softens, and nobody notices until a sponsor asks why last week’s merge was green and this week’s field window is not.
Three drift patterns show up often:
-
Different URLs. CI protects
/on the preview host. The retainer reports/checkouton production. - Different clocks. CI is lab-only. The client pack mixes CrUX categories without labelling the window.
- Different owners. Developers change assertions without telling account leads; account leads invent “good enough” bands for a sales deck.
Performance budgets are the contract that stops that drift. web.dev’s performance budgets 101 frames them as limits you set before you ship. Agencies need one more step: the same limits must survive the handoff from demo to retained delivery.
One threshold language both sides keep
Start with Core Web Vitals in the same units Google already publishes, then add supporting lab metrics only if someone will act on them.
| Metric | Example mobile budget (lab) | Why both sides care |
|---|---|---|
| LCP | ≤ 2.5 s | Hero and checkout speed sponsors recognise |
| INP | ≤ 200 ms | Interaction regressions after tag or SPA changes |
| CLS | ≤ 0.1 | Layout shift from banners, embeds, late fonts |
| Performance score (optional) | ≥ 90 on priority URLs | Useful as a CI gate; weaker as the only client KPI |
Write those numbers into a shared sheet once, with owners and review cadence. Lab budgets belong in CI assertions and in scheduled production tests. Field (CrUX) categories sit beside them as a labelled second row, not as a silent override of the lab gate. When CrUX has no data for an origin, say so plainly rather than inventing a green badge from lab alone.
Weight and request-count budgets still help on image-heavy templates. Keep them secondary to CWV language in client conversations unless the engineering team already lives in kilobytes. Official orientation for Lighthouse-based budgets sits in Use Lighthouse for performance budgets; MDN’s Performance budgets guide is a solid companion for the same idea.
The demo → retained budget ritual
Agencies that keep budgets sticky usually run a short ceremony when a new client starts, then refuse to invent new bands every quarter.
1. Demo with production-shaped URLs. Show the money paths you will monitor, not only the homepage. Capture baseline lab numbers and note field availability.
2. Agree thresholds in writing. Use the shared sheet. Name mobile and desktop if both matter. Name who owns a breach (agency sprint vs client tag team).
3. Mirror into Lighthouse CI. Assertions protect merges on the preview URLs that map to those money paths. Do not encode a vanity homepage score that production never measures.
4. Mirror into production schedules. The same LCP / INP / CLS lines become the green and red language in alerts and monthly reports. Scheduled PageSpeed Insights (or equivalent) runs keep history; budgets decide when humans get interrupted.
5. Review on a calendar, not on vibes. Quarterly is enough for most retainers unless a redesign is live. Change a threshold only with a written reason both sides can find later.
That ritual is the product of the retainer. Tools differ. DIY scripts, portfolio monitors, and CI plugins all work when the sheet is the source of truth. Apogee Watcher is built for the production side of that loop (schedules, budgets, alerts across organisations). Keep Lighthouse CI thin for merge gates either way.
What stays in CI versus what stays on production schedules
| Job | Belongs in Lighthouse CI | Belongs on production monitoring |
|---|---|---|
| Block a bad merge | Yes | No |
| Catch regressions after deploy or tag changes | Weak alone | Yes |
| Multi-tenant client reporting | No | Yes |
| CrUX / field context | Rarely | Yes, labelled |
| Same LCP ≤ 2.5 s language | Yes (assertions) | Yes (budgets + reports) |
CI answers: “May this change ship?” Production monitoring answers: “Is the live portfolio still inside the contract?” Confusing the two jobs produces either enormous workflows or neglected configurations. Keep both; share the threshold language. When account leads can point at the same LCP band the pipeline just enforced, the retainer review stops sounding like two different products.
FAQ
What are performance budgets in a web performance sense?
Numeric limits for page experience (and sometimes weight or request counts) that you set before shipping and reuse when something regresses. In agency retainers they should match the Core Web Vitals language you put in client reports.
How do performance budget thresholds differ from a vague “keep PageSpeed high” promise?
Thresholds name metric, strategy, URL set, and pass/fail band. Vague promises invite taste debates. Use a shared template so account leads are not inventing bands per deck.
Should Lighthouse CI performance budgets match production budgets exactly?
Match the metrics and bands that matter commercially. Preview hosts may differ slightly from production; document that. Do not run a 95 score gate in CI while the retainer quietly accepts 70 on checkout.
Do Core Web Vitals budgets replace Search Console?
No. Budgets organise lab (and optionally field) pass/fail for delivery. Search Console remains a field and indexing source for many SEO conversations. Use both with clocks labelled.
Who owns a budget breach?
Decide at kick-off. Tag-manager and marketing-pixel breaches often sit with the client. Theme and critical-path breaches often sit with the agency. Write the split once so the alert does not become a blame meeting.
CTA
Pick one retainer client this week. Export or write a one-page threshold sheet for three money-path URLs, wire the same LCP / INP / CLS bands into Lighthouse CI, and reuse those bands on whatever production schedule you already run. When you need the CI assertion path in detail, follow performance budgets in CI/CD pipelines. When you need a blank sheet, use the performance budget thresholds template.
Portfolio schedules and budget alerts without a private spreadsheet of PageSpeed tabs are what Apogee Watcher is built for. Keep your merge gates. The sheet you agree with the client is still the source of truth either way.
References
- Performance budgets 101 (web.dev)
- Use Lighthouse for performance budgets (web.dev)
- Performance budgets (MDN)
- Start Performance Budgeting (Addy Osmani)
- How to Set Up Performance Budgets in CI/CD Pipelines (Apogee Watcher)
- Performance Budget Thresholds Template (Apogee Watcher)
- Understanding Core Web Vitals and Google search results (Google Search Central)
Top comments (0)