Driving Team Performance Budget Adoption #

A performance gate fails not when the threshold is wrong but when the team routes around it. Someone adds a // eslint-disable-equivalent override, an admin force-merges past a red check "to unblock the release," and within a quarter the gate asserts a number nobody believes. This is the human layer of the Dashboarding & Team Adoption reference: it covers the ownership model, the written policy, and the review rituals that make a budget survive contact with a shipping team. The technical gate is the easy part — Lighthouse CI will happily exit non-zero. The work here is making that non-zero exit feel like a guardrail the team installed for itself rather than a tax an outside party levied on it.

Adoption is an engineering problem with a measurable outcome: the percentage of budget breaches that get fixed before merge versus the percentage that get waved through. Every practice below — naming an owner, writing the policy, ramping warn to error, running a blameless triage — exists to move that ratio toward fixed-before-merge without breeding the resentment that turns a gate into theater.

The Adoption Lifecycle #

Budget adoption moves through four stages, and skipping any one of them produces a predictable failure. A team that jumps straight to a blocking error-level gate without an observation period and an owner gets the force-merge culture described above. The diagram below maps the lifecycle and the responsibility at each stage.

Prerequisites & Environment #

Before driving adoption you need three things in place: a working gate, a data source, and a named owner. The gate is the Lighthouse CI assertion job calibrated in Lighthouse CI Configuration & Storage; without it there is nothing to adopt. The data source is the dashboard and history from the parent reference, so the team can see trends rather than argue about anecdotes. The owner is a single accountable role — typically a performance lead or a rotating champion — recorded in the policy, because a budget owned by "everyone" is owned by no one.

• A green Lighthouse CI job that produces per-metric assertions on every pull request.
• Branch protection available on the default branch, so a check can be marked required.
• A CODEOWNERS file the team already respects for review routing.
• A retained baseline of at least two weeks so warn-level thresholds reflect real variance, not a single lucky build.

Configuration Reference — Budget Policy Template #

The policy is the contract. It names the owner, lists the thresholds, and defines the exception workflow so a breach has a documented path that is not "force-merge." Keep it in the repository next to the gate config as PERFORMANCE_BUDGET.yml so it versions with the code it governs.

# PERFORMANCE_BUDGET.yml — the team's performance contract
version: 1
owner: "@frontend-platform"          # accountable team, never an individual
review_cadence: "quarterly"          # recalibrate thresholds against field data

budgets:
  - route: "/"
    device: "mid-range-mobile"       # Moto G-class
    connection: "fast-3g"
    metrics:
      lcp_ms:   { target: 2500, level: error }   # P75 field ceiling
      inp_ms:   { target: 200,  level: error }
      cls:      { target: 0.10, level: error }
      script_kb:{ target: 170,  level: error }
  - route: "/checkout"
    device: "mid-range-mobile"
    connection: "fast-3g"
    metrics:
      lcp_ms:   { target: 2800, level: warn }     # newer route, still calibrating

exceptions:
  process: "open a budget-exception PR tagging the owner"
  requires: ["named justification", "expiry date <= 30 days", "tracking issue"]
  default_level_on_new_metric: warn               # never ship a new metric as error

Every threshold carries a level so the same file expresses both the soft and hard gate. A metric at warn produces a comment; a metric at error blocks the merge. New metrics always enter at warn so the team is never surprised by a gate they did not see coming.

Step-by-Step Rollout #

1. Observe (week 1–2). Run the gate in non-blocking mode and collect a baseline. Confirm the median is stable.

   npx lhci autorun --collect.numberOfRuns=5 --upload.target=lhci

   Expected output: All results processed! with a stored build you can chart. No merge is blocked yet.

2. Warn (week 3–4). Flip the assertions to warn and post the result as a PR comment so the team sees the budget without being blocked by it.

   npx lhci assert --preset=lighthouse:no-pwa --assertions.metric-lcp.0=warn

   Expected: a non-zero-free run that prints ⚠ lines for any breach but exits 0.

3. Enforce (week 5+). Promote stable metrics to error, mark the check required in branch protection, and add the owner to CODEOWNERS for the budget file. From here a breach is unmergeable without an exception PR.

4. Sustain. Run a recurring blameless triage on the dashboard. Treat every regression as a process question — "what let this through?" — not a person question, and recalibrate thresholds quarterly against fresh field percentiles.

Threshold Calibration — Warn to Error Ramp #

The ramp from warn to error is what earns the gate trust. Promote a metric to blocking only after its threshold has held without false positives, so the first time the gate blocks a merge it is unambiguously catching a real regression. Promoting too early — before the variance is understood — produces the flaky red check that the team learns to ignore.

The exception row matters as much as the enforce row. A team with no legitimate escape hatch invents an illegitimate one. The statistical basis for deciding a regression is real rather than noise comes from Automated Regression Detection; use it to set the soak criterion above.

CI Enforcement Snippet #

Two mechanisms make the gate real: a required status check and codeowner review on the budget file so thresholds cannot be quietly loosened. The workflow runs the assertion; CODEOWNERS guards the policy.

# .github/workflows/perf-gate.yml
name: Performance Budget Gate
on:
  pull_request:
    branches: [main]

jobs:
  budget:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20", cache: "npm" }
      - run: npm ci && npm run build
      - name: Assert performance budget
        run: npx lhci autorun
        env:
          LHCI_TOKEN: ${{ secrets.LHCI_TOKEN }}
          LHCI_SERVER_BASE_URL: ${{ secrets.LHCI_SERVER_BASE_URL }}

# CODEOWNERS — changing the budget requires the owner's review
/PERFORMANCE_BUDGET.yml   @frontend-platform
/lighthouserc.json        @frontend-platform

Mark the budget job a required check in branch protection. Now loosening a threshold means editing PERFORMANCE_BUDGET.yml, which triggers a review by @frontend-platform — the change is visible, attributable, and discussable, which is exactly what budget erosion is not. The concrete policy document this enforces is written in Writing a Performance Budget Policy.

Troubleshooting & Edge Cases #

• The gate gets bypassed by force-merge. Disable admin bypass in branch protection or require an exception PR; if leadership keeps overriding, the budget lacks executive sponsorship, which is a sponsorship problem, not a tooling one.
• Team pushback that the budget blocks velocity. Move the offending metric back to warn, show the dashboard trend, and re-promote only after the soak criterion passes — resentment usually traces to a flaky check, not the budget itself.
• A single noisy route trips the gate randomly. Raise numberOfRuns, fix the variance at its source, and keep that route at warn until it stabilizes rather than weakening the global threshold.
• Exceptions never expire. Add a CI check that fails any waiver past its expiry date so time-boxed exceptions are actually time-boxed.
• Ownership evaporates after a reorg. Because the owner is a team handle in CODEOWNERS, reassign the handle rather than re-adopting from scratch.
• New routes ship with no budget. Default new metrics to warn and require a budget entry before a route reaches error, so coverage grows with the codebase.

Frequently Asked Questions #