> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/GoogleChrome/lighthouse/llms.txt
> Use this file to discover all available pages before exploring further.

# CI Integration

> Run Lighthouse automatically on every commit to catch performance regressions before they reach production.

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](https://github.com/GoogleChrome/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.

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install --save-dev @lhci/cli
    ```
  </Step>

  <Step title="Create a configuration file">
    Add `lighthouserc.json` to the root of your repository:

    ```json lighthouserc.json theme={null}
    {
      "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`).
  </Step>

  <Step title="Add the CI commands to your pipeline">
    ```bash theme={null}
    npx lhci autorun
    ```

    `autorun` runs `collect`, `assert`, and `upload` in sequence using your `lighthouserc.json`.
  </Step>
</Steps>

## GitHub Actions example

The `treosh/lighthouse-ci-action` wraps Lighthouse CI for use in GitHub Actions workflows.

```yaml .github/workflows/lighthouse.yml theme={null}
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.

<CodeGroup>
  ```bash CLI theme={null}
  lighthouse https://example.com \
    --output=json \
    --output-path=./reports/lighthouse.json \
    --chrome-flags="--headless --no-sandbox --disable-gpu"
  ```

  ```yaml GitHub Actions step theme={null}
  - name: Run Lighthouse
    run: |
      npx lighthouse https://example.com \
        --output=json \
        --output-path=./reports/lighthouse.json \
        --chrome-flags="--headless --no-sandbox --disable-gpu"

  - name: Upload report
    uses: actions/upload-artifact@v4
    with:
      name: lighthouse-report
      path: reports/lighthouse.json
  ```
</CodeGroup>

## Speeding up CI runs

Use `--only-categories` to skip audits you do not need. Auditing only performance is significantly faster than a full run.

```bash theme={null}
lighthouse https://example.com \
  --only-categories=performance \
  --output=json \
  --output-path=./reports/performance.json
```

Available categories: `performance`, `accessibility`, `best-practices`, `seo`.

<Tip>
  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.
</Tip>

## Third-party integrations

Several commercial services run Lighthouse on your behalf, removing the need to manage your own CI infrastructure:

* **[WebPageTest](https://www.webpagetest.org)** — Runs Lighthouse alongside waterfall and filmstrip analysis. Supports real devices across multiple locations.
* **[Calibre](https://calibreapp.com)** — Continuous performance monitoring with GitHub pull request reviews, performance budgets, and a developer API.
* **[DebugBear](https://www.debugbear.com)** — Tracks Lighthouse scores and metrics over time with a focus on identifying the cause of each change.
* **[Treo](https://treo.sh)** — Lighthouse as a service with regression testing, custom networks, and GitHub and Slack integrations.