Integrations

unlighthouse-ci: Bulk Lighthouse CI for Entire Sites

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:

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 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