--- title: "unlighthouse-ci: Bulk Lighthouse CI for Entire Sites" icon: i-carbon-terminal-3270 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." keywords: - unlighthouse-ci - unlighthouse ci - unlighthouse github actions - unlighthouse gitlab ci - bulk lighthouse ci - site-wide lighthouse ci - lighthouse ci entire site - lighthouse ci bulk - lighthouse performance budget - ci cd lighthouse bulk navigation: title: "CI/CD" relatedPages: - path: /integrations/cli title: CLI Integration - path: /guide/guides/generating-static-reports title: Static Reports - path: /glossary title: Core Web Vitals Guide --- ## 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: ```bash npm install -g @unlighthouse/cli 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 ```bash # 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: ```bash 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. You do not need to install `puppeteer`: ```bash npm install -g @unlighthouse/cli ``` Unlighthouse uses the system Chrome. If it finds none, it downloads a compatible Chrome to `~/.unlighthouse`. See [Chrome Dependency](/guide/guides/chrome-dependency). ## Performance Budgets ### Simple: One Number ```bash # Fail if ANY category on ANY page < 75 unlighthouse-ci --site example.com --budget 75 ``` ### Per-Category Budgets More control in your config: ```ts // 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: ```bash 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` | ```bash # Generate CSV for stakeholders unlighthouse-ci --site example.com --reporter csvExpanded ``` ## Static Reports Generate a shareable HTML dashboard: ```bash 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 ` | Host URL to scan. | | `--root ` | Define the project root. Useful for changing where the config is read from or setting up sampling. | | `--config-file ` | Path to config file. | | `--output-path ` | Path to save the contents of the client and reports to. | | `--budget ` | Budget (1-100), the minimum score which can pass. | | `--reporter ` | The report to generate from results. Options: csv, csvExpanded, json, jsonExpanded, lighthouseServer or false. Default: jsonSimple. | | `--lhci-host ` | URL of your LHCI server. | | `--lhci-build-token ` | LHCI build token, used to add data. | | `--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 ` | Specify a top-level user agent all requests will use. | | `--router-prefix ` | The URL path prefix for the client and API to run from. | | `--throttle` | Enable the throttling. | | `--samples ` | Specify the amount of samples to run. | | `--sitemaps ` | Comma separated list of sitemaps to use for scanning. Providing these will override any in robots.txt. | | `--urls ` | Specify explicit relative paths to scan as a comma-separated list, disabling the link crawler. | | `--exclude-urls ` | Route patterns to exclude as a comma-separated list, such as `/admin/**`. Not regex. | | `--include-urls ` | Route patterns to include as a comma-separated list, such as `/,/blog/**`. Not regex. | | `--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 ` | Extra headers to send with the request. Example: --extra-headers foo=bar,bar=foo | | `--cookies ` | Cookies to send with the request. Example: --cookies foo=bar;bar=foo | | `--auth ` | Basic auth to send with the request. Example: --auth username:password | | `--default-query-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. ```ts 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. ```yml unlighthouse.yml 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 netlify-cli - name: Unlighthouse assertions and client run: unlighthouse-ci --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 ```yaml # .gitlab-ci.yml lighthouse-audit: image: node:22 script: - npm install -g @unlighthouse/cli - unlighthouse-ci --site $SITE_URL --budget 75 artifacts: paths: - .unlighthouse/ expire_in: 1 week ``` ## CircleCI Example ```yaml # .circleci/config.yml version: 2.1 jobs: lighthouse: docker: - image: cimg/node:22.18.0-browsers steps: - checkout - run: npm install -g @unlighthouse/cli - run: unlighthouse-ci --site $SITE_URL --budget 75 --build-static - store_artifacts: path: .unlighthouse ```