Skip to main content
Running Lighthouse in CI gives you a signal for every commit: did performance improve, regress, or hold steady? Catching regressions in a pull request is far cheaper than diagnosing them in production.

​
Lighthouse CI (official)

Lighthouse CI is the official tool for automating Lighthouse in continuous integration. It collects reports, stores them per commit, surfaces regressions in pull requests, and compares results against a baseline.
1

Install the CLI

npm install --save-dev @lhci/cli
2

Create a configuration file

Add lighthouserc.json to the root of your repository:
lighthouserc.json
{
  "ci": {
    "collect": {
      "url": ["https://example.com", "https://example.com/about"],
      "numberOfRuns": 3
    },
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "categories:performance": ["warn", { "minScore": 0.9 }],
        "categories:accessibility": ["error", { "minScore": 1 }]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}
  • numberOfRuns collects multiple reports per URL and uses the median, which reduces noise.
  • assert fails the CI run when scores drop below the specified thresholds.
  • upload posts a link to the report in pull request comments (requires the LHCI server or temporary-public-storage).
3

Add the CI commands to your pipeline

npx lhci autorun
autorun runs collect, assert, and upload in sequence using your lighthouserc.json.

​
GitHub Actions example

The treosh/lighthouse-ci-action wraps Lighthouse CI for use in GitHub Actions workflows.
.github/workflows/lighthouse.yml
name: Lighthouse CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Lighthouse CI
        uses: treosh/lighthouse-ci-action@v11
        with:
          urls: |
            https://example.com
            https://example.com/about
          budgetPath: ./budget.json
          uploadArtifacts: true
          temporaryPublicStorage: true
The action uploads reports as GitHub Actions artifacts and posts a summary comment on the pull request when temporaryPublicStorage is enabled.

​
Saving reports as artifacts

Use --output=json and --output-path to write a report file that can be stored as a CI artifact for later review. 
lighthouse https://example.com \
  --output=json \
  --output-path=./reports/lighthouse.json \
  --chrome-flags="--headless --no-sandbox --disable-gpu"

​
Speeding up CI runs

Use --only-categories to skip audits you do not need. Auditing only performance is significantly faster than a full run. 
lighthouse https://example.com \
  --only-categories=performance \
  --output=json \
  --output-path=./reports/performance.json
Available categories: performance, accessibility, best-practices, seo.
Run Lighthouse at least 3 times per URL (numberOfRuns: 3 in lighthouserc.json) and use the median score for assertions. A single run is not reliable enough to gate a deploy — a brief network hiccup or CPU spike can produce a falsely low score. The median of multiple runs is approximately twice as stable as a single run.

​
Third-party integrations

Several commercial services run Lighthouse on your behalf, removing the need to manage your own CI infrastructure:
  • WebPageTest — Runs Lighthouse alongside waterfall and filmstrip analysis. Supports real devices across multiple locations.
  • Calibre — Continuous performance monitoring with GitHub pull request reviews, performance budgets, and a developer API.
  • DebugBear — Tracks Lighthouse scores and metrics over time with a focus on identifying the cause of each change.
  • Treo — Lighthouse as a service with regression testing, custom networks, and GitHub and Slack integrations.

Build docs developers (and LLMs) love

Get started for freeTalk to us