---
title: "Lighthouse CI (LHCI) Integration · Unlighthouse"
meta:
  "og:description": "Run Lighthouse CI on your entire site. Automate site-wide audits in GitHub Actions, GitLab CI, and any CI/CD pipeline with budget assertions."
  "og:title": "Lighthouse CI (LHCI) Integration · Unlighthouse"
  description: "Run Lighthouse CI on your entire site. Automate site-wide audits in GitHub Actions, GitLab CI, and any CI/CD pipeline with budget assertions."
---

**Integrations**

# **Lighthouse CI (LHCI) Integration**

[Copy for LLMs](https://unlighthouse.dev/integrations/ci.md)

Run Lighthouse on every deploy. Catch performance regressions before they hit production.

```
npm install -g @unlighthouse/cli puppeteer
unlighthouse-ci --site https://staging.example.com --budget 80
```

If any page scores below 80, the command exits with code 1—failing your CI build.

## [Why Unlighthouse CI?](#why-unlighthouse-ci)

|  | **Google LHCI** | **Unlighthouse CI** |
| --- | --- | --- |
| **Setup** | Complex config, URL manifest | One command |
| **Pages** | Manual list | Auto-discovers entire site |
| **Budgets** | Per-page config | Single threshold for all pages |
| **Reports** | JSON/HTML | Interactive dashboard, JSON, CSV |

## [Basic Usage](#basic-usage)

```
# Scan site, fail if any page < 75
unlighthouse-ci --site example.com --budget 75

# Generate static HTML report
unlighthouse-ci --site example.com --build-static

# Both: budget check + report
unlighthouse-ci --site example.com --budget 75 --build-static
```

## [Already Using LHCI Server?](#already-using-lhci-server)

Keep your existing infrastructure—Unlighthouse uploads to LHCI servers:

```
unlighthouse-ci --site example.com \
  --reporter lighthouseServer \
  --lhci-host https://lhci.yourcompany.com \
  --lhci-build-token $LHCI_TOKEN
```

## [Installation for CI](#installation-for-ci)

CI environments need Chrome. Install puppeteer alongside the CLI:

```
npm install -g @unlighthouse/cli puppeteer
```

Puppeteer downloads a compatible Chromium binary automatically.

## [Performance Budgets](#performance-budgets)

### [Simple: One Number](#simple-one-number)

```
# Fail if ANY category on ANY page < 75
unlighthouse-ci --site example.com --budget 75
```

### [Per-Category Budgets](#per-category-budgets)

More control in your config:

```
// unlighthouse.config.ts
export default defineUnlighthouseConfig({
  site: 'https://example.com',
  ci: {
    budget: {
      'performance': 70, // Performance can be lower
      'accessibility': 95, // Accessibility must be high
      'best-practices': 80,
      'seo': 90,
    },
  },
})
```

Run with just:

```
unlighthouse-ci
```

## [Report Formats](#report-formats)

| **Format** | **Use Case** | **Flag** |
| --- | --- | --- |
| `json` | Simple scores for CI parsing | `--reporter json` |
| `jsonExpanded` | Full metrics breakdown | `--reporter jsonExpanded` |
| `csv` | Spreadsheet analysis | `--reporter csv` |
| `csvExpanded` | Full data in CSV | `--reporter csvExpanded` |
| `lighthouseServer` | Upload to LHCI server | `--reporter lighthouseServer` |

```
# Generate CSV for stakeholders
unlighthouse-ci --site example.com --reporter csvExpanded
```

## [Static Reports](#static-reports)

Generate a shareable HTML dashboard:

```
unlighthouse-ci --site example.com --build-static
```

Output goes to `.unlighthouse/`. Upload that folder to any static host.

**Live examples:**

- [**inspect.unlighthouse.dev**](https://inspect.unlighthouse.dev/)
- [**vue-demo.unlighthouse.dev**](https://vue-demo.unlighthouse.dev/)

## [Configuration](#configuration)

Configuring the CLI can be done either through the CI arguments or through a config file.

### [CI Options](#ci-options)

| **Options** | |
| --- | --- |
| `-v, --version` | Display version number. |
| `--site <url>` | Host URL to scan. |
| `--root <path>` | Define the project root. Useful for changing where the config is read from or setting up sampling. |
| `--config-file <path>` | Path to config file. |
| `--output-path <path>` | Path to save the contents of the client and reports to. |
| `--budget <budget>` | Budget (1-100), the minimum score which can pass. |
| `--reporter <reporter>` | The report to generate from results. Options: csv, csvExpanded, json, jsonExpanded, lighthouseServer or false. Default: jsonSimple. |
| `--lhci-host <lhci-host>` | URL of your LHCI server. |
| `--lhci-build-token <lhci-build-token>` | LHCI build token, used to add data. |
| `--lhci-auth <lhci-auth>` | Basic auth for your LHCI server. |
| `--build-static` | Build a static website for the reports which can be uploaded. |
| `--cache` | Enable the caching. |
| `--no-cache` | Disable the caching. |
| `--desktop` | Simulate device as desktop. |
| `--mobile` | Simulate device as mobile. |
| `--user-agent <user-agent>` | Specify a top-level user agent all requests will use. |
| `--router-prefix <path>` | The URL path prefix for the client and API to run from. |
| `--throttle` | Enable the throttling. |
| `--samples <samples>` | Specify the amount of samples to run. |
| `--sitemaps <sitemaps>` | Comma separated list of sitemaps to use for scanning. Providing these will override any in robots.txt. |
| `--urls <urls>` | Specify explicit relative paths to scan as a comma-separated list, disabling the link crawler. |
| `--exclude-urls <urls>` | Relative paths (string or regex) to exclude as a comma-separated list. |
| `--include-urls <urls>` | Relative paths (string or regex) to include as a comma-separated list. |
| `--enable-javascript` | When inspecting the HTML wait for the javascript to execute. Useful for SPAs. |
| `--disable-javascript` | When inspecting the HTML, don't wait for the javascript to execute. |
| `--enable-i18n-pages` | Enable scanning pages which use x-default. |
| `--disable-i18n-pages` | Disable scanning pages which use x-default. |
| `--disable-robots-txt` | Disables the robots.txt crawling. |
| `--disable-sitemap` | Disables the sitemap.xml crawling. |
| `--disable-dynamic-sampling` | Disables the sampling of paths. |
| `--extra-headers <headers>` | Extra headers to send with the request. Example: --extra-headers foo=bar,bar=foo |
| `--cookies <cookies>` | Cookies to send with the request. Example: --cookies foo=bar;bar=foo |
| `--auth <auth>` | Basic auth to send with the request. Example: --auth username:password |
| `--default-query-params <params>` | Default query params to send with the request. Example: --default-query-params foo=bar,bar=foo |
| `-d, --debug` | Debug. Enable debugging in the logger. |
| `-h, --help` | Display available CLI options |

### [Config File](#config-file)

If you want to configure Unlighthouse, you can create a `unlighthouse.config.ts` file in your cwd.

```
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'example.com',
  debug: true,
  scanner: {
    device: 'desktop',
  },
})
```

See the [**Configuration**](#configuration) section for more details and the guides.

## [GitHub Actions & Netlify Example](#github-actions-netlify-example)

This example is for GitHub Actions and deploys a static client build to Netlify.

```
name: Assertions and static report

on:
  workflow_dispatch:

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Dependencies
        run: npm install -g @unlighthouse/cli puppeteer netlify-cli

      - name: Unlighthouse assertions and client
        run: unlighthouse-ci --site <your-site> --budget 75 --build-static

      - name: Deploy
        run: netlify deploy --dir=.unlighthouse --prod --message="New Release Deploy from GitHub Actions"
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
```

## [GitLab CI Example](#gitlab-ci-example)

```
# .gitlab-ci.yml
lighthouse-audit:
  image: node:20
  script:
    - npm install -g @unlighthouse/cli puppeteer
    - unlighthouse-ci --site $SITE_URL --budget 75
  artifacts:
    paths:
      - .unlighthouse/
    expire_in: 1 week
```

## [CircleCI Example](#circleci-example)

```
# .circleci/config.yml
version: 2.1
jobs:
  lighthouse:
    docker:
      - image: cimg/node:20.0-browsers
    steps:
      - checkout
      - run: npm install -g @unlighthouse/cli
      - run: unlighthouse-ci --site $SITE_URL --budget 75 --build-static
      - store_artifacts:
          path: .unlighthouse
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/1.ci.md)

[Markdown For LLMs](https://unlighthouse.dev/integrations/ci.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/1.ci.md) on GitHub or provide anonymous feedback below.

[**CLI** Scan your entire website with Lighthouse from the command line. Alternative to lighthouse CLI that audits all pages automatically.](https://unlighthouse.dev/integrations/cli) [**Nuxt** Integrate Lighthouse audits directly into your Nuxt development workflow with automatic route discovery.](https://unlighthouse.dev/integrations/nuxt)

**On this page **

- [Why Unlighthouse CI?](#why-unlighthouse-ci)
- [Basic Usage](#basic-usage)
- [Already Using LHCI Server?](#already-using-lhci-server)
- [Installation for CI](#installation-for-ci)
- [Performance Budgets](#performance-budgets)
- [Report Formats](#report-formats)
- [Static Reports](#static-reports)
- [Configuration](#configuration)
- [GitHub Actions & Netlify Example](#github-actions-netlify-example)
- [GitLab CI Example](#gitlab-ci-example)
- [CircleCI Example](#circleci-example)