---
title: "unlighthouse-ci: Bulk Lighthouse CI for Entire Sites · Unlighthouse"
meta:
  description: "Run unlighthouse-ci on every deploy. Auto-discovers every URL, runs Lighthouse on all of them in parallel, enforces a single budget. Works in GitHub Actions, GitLab CI, any pipeline."
  "og:description": "Run unlighthouse-ci on every deploy. Auto-discovers every URL, runs Lighthouse on all of them in parallel, enforces a single budget. Works in GitHub Actions, GitLab CI, any pipeline."
  "og:title": "unlighthouse-ci: Bulk Lighthouse CI for Entire Sites · Unlighthouse"
---

</h1>

```

Unlighthouse on GitHub

**Integrations**# **unlighthouse-ci: Bulk Lighthouse CI for Entire Sites**[Copy for LLMs](https://unlighthouse.dev/integrations/ci.md) ## Run `**unlighthouse-ci**` in your pipeline The `**unlighthouse-ci**` binary runs Lighthouse on every page of your site and fails your CI build if any score drops below a budget:```
npm install -g @unlighthouse/cli puppeteer
unlighthouse-ci --site https://staging.example.com --budget 80
``` Exit code 1 = budget failed. Exit code 0 = all pages passed. That's the entire contract. Wire this single command into GitHub Actions, GitLab CI, CircleCI, or any pipeline that runs bash. ## 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```
# 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? 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 CI environments need Chrome. Install puppeteer alongside the CLI:```
npm install -g @unlighthouse/cli puppeteer
``` Puppeteer downloads a compatible Chromium binary automatically. ## Performance Budgets ### Simple: One Number```
# Fail if ANY category on ANY page < 75
unlighthouse-ci --site example.com --budget 75
```### 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 | **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 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 Configuring the CLI can be done either through the CI arguments or through a config file. ### 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 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 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.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/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. ### **Related **[**CLI Integration**](https://unlighthouse.dev/integrations/cli) [**Static Reports**](https://unlighthouse.dev/guide/guides/generating-static-reports) [**Core Web Vitals Guide**](https://unlighthouse.dev/glossary) [**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 **- [Run unlighthouse-ci in your pipeline](#run-unlighthouse-ci-in-your-pipeline) - [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)