How to Set Up Web Performance Budgets in CI/CD Pipelines for SEO

Site speed is not a static attribute. Even if your website achieves a perfect 100/100 Core Web Vitals score today, it will naturally slow down over time as developers add new features, marketers embed tracking scripts, and editors upload unoptimized media. This gradual slowdown is known as performance decay.

Rather than waiting for your organic traffic to drop or Google Search Console to flag pages for slow speeds, you can prevent performance issues by using Web Performance Budgets. By integrating automated audits into your Continuous Integration and Continuous Deployment (CI/CD) pipelines, you can block slow code updates before they are ever deployed to production.

---

1. Defining Your Performance Budget

A performance budget sets specific limits for your web pages. Budgets generally fall into two categories:

1. Resource Budgets (Asset Sizes)

These budgets set limits on the size and quantity of your files.

• →JavaScript Budget: Max 150KB (compressed/gzipped) for the initial bundle.
• →CSS Budget: Max 50KB total.
• →Image Budget: Max 800KB total above-the-fold image payload.
• →Fonts Budget: Max 100KB total.

2. Metric Budgets (User Milestones)

These budgets set limits on the Core Web Vitals timings recorded in a simulated testing environment.

• →Largest Contentful Paint (LCP): Under 2.5 seconds.
• →Total Blocking Time (TBT): Under 200 milliseconds.
• →Cumulative Layout Shift (CLS): Under 0.1.

---

2. Configuring Lighthouse CI (.lighthouserc.json)

Lighthouse CI (LHCI) is an open-source suite of tools that runs Google Lighthouse audits on your server containers during the build process.

To configure Lighthouse CI, create a .lighthouserc.json file in the root directory of your project:

{
  "ci": {
    "collect": {
      "numberOfRuns": 3,
      "staticDistDir": "./.next"
    },
    "assert": {
      "assertions": {
        "categories:performance": ["error", {"minScore": 0.90}],
        "categories:seo": ["error", {"minScore": 0.95}],
        "first-contentful-paint": ["warn", {"maxNumericValue": 1800}],
        "largest-contentful-paint": ["error", {"maxNumericValue": 2500}],
        "cumulative-layout-shift": ["error", {"maxNumericValue": 0.10}],
        "total-blocking-time": ["error", {"maxNumericValue": 200}],
        "resource-summary:document:size": ["error", {"maxNumericValue": 100000}],
        "resource-summary:script:size": ["error", {"maxNumericValue": 200000}]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

In this configuration:

• →numberOfRuns: 3 runs Lighthouse three times and averages the results to reduce variance in cloud environments.
• →The assertions block defines the passing criteria. Any audit that falls below these thresholds (such as an LCP over 2.5s or a performance score below 90) will trigger an exit code error that fails the build.

---

3. Automating Audits with GitHub Actions

With your budget config in place, you can write a GitHub Actions workflow to run the audits on every pull request.

Create a file named .github/workflows/lighthouse-ci.yml in your project repository:

name: Web Performance CI

on:
  pull_request:
    branches: [ main, master ]

jobs:
  performance-audit:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Code Repository
      uses: actions/checkout@v3

    - name: Set Up Node.js Environment
      uses: actions/setup-node@v3
      with:
        node-cache: 'npm'
        node-version: 18

    - name: Install Dependencies
      run: npm ci

    - name: Compile Production Build
      run: npm run build

    - name: Install Lighthouse CI CLI
      run: npm install -g @lhci/[email protected]

    - name: Run Lighthouse CI Audits
      run: lhci autorun
      env:
        LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

How the Workflow Protects Production:

1. Code Commit: A developer submits a pull request containing changes (like adding a third-party tracking pixel).
2. Pipeline Trigger: GitHub Actions checks out the code, installs dependencies, and runs npm run build to compile the Next.js site.
3. Lighthouse Run: Lighthouse CI runs audits against the static output.
4. Assertion Check: If the tracking script increases TBT past 200ms or drops the performance score below 90, Lighthouse CI triggers a build error.
5. Merge Blocked: GitHub prevents the pull request from being merged until the developer resolves the performance issue.

---

4. Best Practices for Maintaining Performance Budgets

• →Establish Baseline Metrics: Run tests on your existing production site to establish realistic baseline budgets. Do not set overly restrictive budgets initially; start with moderate limits and tighten them as performance improves.
• →Test on Mobile Viewports: Always configure your Lighthouse CI tests to emulate mobile devices. Since mobile hardware is slower and relies on cellular connections, a build that passes on desktop can easily fail on mobile.
• →Account for Shared Hosting Variance: Shared CI runners (like GitHub's free runners) can have fluctuating CPU speeds. Use multiple testing runs (numberOfRuns: 3) to average out variations and prevent false build failures.

---

Official References

• →Google Lighthouse CI Documentation Repository
• →web.dev: Performance Budgets 101
• →W3C Web Performance Working Group
• →Google Developers: Web Vitals Documentation