# Speed budgets: setting one and holding to it in CI > Pick a speed budget from your own numbers, write it into the repo and make the build fail when a pull request breaks it, with Lighthouse CI configs and a budgets.json for a shop and a marketing site. Updated 2026-09-25 · Speed & Core Web Vitals · HTML version: https://getreport.app/guides/speed-budgets-setting-one-and-holding-to-it-in-ci A site gets slow the way a room gets untidy: one chat widget, one hero video, one more font, each of them reasonable on its own. A speed budget is the line you agree not to cross, written down, and checked by a machine on every change. This guide shows how to pick numbers you can defend, how to hold them in CI without false alarms, and what to do on the day a pull request breaks them. Setting it up takes an afternoon; keeping it costs a few minutes a month. ## Quick answer - A budget is a limit on a **metric** (LCP under 2.5 s on a mid-range phone), a **quantity** (JavaScript under 300 KB, images under 1 MB, at most 5 third parties) or a **rule** (no synchronous script in ``). - Start from where you are: run the [speed test](https://getreport.app/tools/speed-test) on one page per template and read the field p75 in the Core Web Vitals history. Set each budget at the current value minus a margin and tighten it quarterly. - Enforce quantities as errors (bytes and request counts are stable between runs) and metrics as warnings (lab timings vary run to run). - Use Lighthouse CI with `assertions` or a `budgets.json`, run 3–5 times against a preview URL, and take the median. - Keep the budget file in the repo, with a named owner for every increase. - getReport is the monthly human check; Lighthouse CI is the per-commit machine check. The getReport API is announced for a later milestone and is not live, so do not plan a CI step on it yet. ## Why a speed budget matters Without a budget, every speed fix is temporary. Someone spends a week getting LCP to 2.1 s, and six months later the marketing team has added a video background, a review carousel and two tracking pixels, and it is 3.8 s again. Nobody did anything wrong; nobody was watching the total. The [40-week Core Web Vitals history](https://getreport.app/guides/core-web-vitals-history-40-weeks) of most sites shows exactly this shape: a dip after a fix, then a slow climb. A budget turns speed from a project into a property of the site. It also changes the conversation. "Can we add the chat widget?" becomes "The chat widget costs 180 KB and 90 ms of blocking; the third-party budget has 60 KB left, so what comes out?" A marketer and a developer can settle that in a minute. The number is not the point; the habit is. A generous budget that is enforced beats a strict one that is not. ## How getReport checks it > **Free tool:** [Website speed test](https://getreport.app/tools/speed-test): Lighthouse lab results and real-user Core Web Vitals for any page, mobile and desktop, with a filmstrip, a request waterfall and a fix for every slow part. Free, no signup. The speed test runs Google's Lighthouse on a throttled phone and on desktop and shows the real-user Core Web Vitals from the Chrome UX Report beside the lab numbers. Four findings from it are the ones a budget is built on: > **Check: Lighthouse performance score.** This is the number Google's own tools show for your page. It combines five of the lab metrics below (all except TTFB), weighted the way Lighthouse weights them. 90 and above is green. > > 1. Work through the failed metrics and opportunities below in order of points; the score follows. > **Check: Total Blocking Time.** TBT adds up every moment the page was too busy running JavaScript to respond to a tap. It is the lab stand-in for INP and the heaviest-weighted Lighthouse metric. > > 1. Remove or defer JavaScript that is not needed for the first screen (defer, async, or load on interaction). > 2. Split long tasks (> 50 ms) into smaller chunks; move heavy work to a web worker. > 3. Audit third-party tags — chat widgets, tag managers and A/B tools are the usual culprits. > **Check: Third-party code weight.** Tags, widgets and embeds from other companies run on your visitors' phones at your page's expense. Over 250 KB or 250 ms of blocking is a sign they dominate the load. > > 1. List what each third party gives you; remove the ones nobody looks at. > 2. Load the rest after interaction or with a facade (a static thumbnail for YouTube, a click-to-load chat button). > 3. Move tags into a tag manager that fires them late, not in . > **Check: Total image weight.** Images are usually the heaviest part of a page. Over 1.5 MB in total, or a single image over 500 KB, adds seconds on mobile and costs visitors real data. > > 1. Resize images to the size they are shown at (a 400 px wide photo does not need a 4000 px file). > 2. Convert to WebP or AVIF and compress to about 80 % quality; CMS plugins and CDNs can do this automatically. The score is an information finding with no weight in getReport's own scoring, and that is deliberate: it is a summary of the metrics, not a metric. [Total Blocking Time](https://getreport.app/learn/total-blocking-time) is the lab stand-in for INP and the metric a JavaScript budget protects. The [third-party](https://getreport.app/learn/third-party-scripts) finding lists each vendor with its transfer size and blocking time (up to ten), and warns when the total passes 250 KB or 250 ms of blocking. The image finding comes from the rendered page's requests, warns above 1.5 MB in total or 500 KB for a single file, and lists the largest files by URL. Those lists are where a broken budget gets a name. For the field side, the [Core Web Vitals history](https://getreport.app/tools/cwv-history) tool plots the weekly 75th percentile of LCP, INP and CLS for the whole origin, or one page, against Google's thresholds: ![Core Web Vitals history for a shop over 40 weeks: one small chart per metric with the weekly p75 line crossing between the green, amber and red bands, and the latest value labelled on each](https://getreport.app/guides/img/speed-budgets-setting-one-and-holding-to-it-in-ci/history.webp "The field p75 per metric, week by week, against Google's bands: this is the number a metric budget should be set from.") The field p75 is what Google ranks on and what your visitors felt. The lab number is what your CI can measure. A budget uses both: the field number decides *what* the target is; the lab number is how you catch a regression *before* it reaches the field. ## Step by step ### 1. Decide which kind of budget you are setting | Kind | Example | Stable in CI? | Use it as | | --- | --- | --- | --- | | Metric | LCP ≤ 2.5 s, TBT ≤ 200 ms, CLS ≤ 0.1 | No: lab timings vary between runs | Warning | | Quantity | JS ≤ 300 KB, images ≤ 1 MB, ≤ 5 third-party origins, ≤ 60 requests | Yes: bytes and counts are the same every run | Error | | Rule | No `