---
title: "CI Integration"
description: "CI Integration for the Unlighthouse v1 beta."
canonical_url: "https://unlighthouse.dev/v1/integrations/ci"
last_updated: "2026-10-03T08:07:18.325Z"
---

The `unlighthouse` beta package includes the `unlighthouse-ci` executable.
Use Node.js 24.13.1 or newer and an installed Chrome browser in your runner.

```sh
pnpm add -D unlighthouse@beta
pnpm exec unlighthouse-ci --site https://staging.example.com --budget 80 --reporter json
```

The runner waits for completion, writes the export, and exits.
A failed budget, failed assertion, or scan with no successful routes returns a nonzero exit code.

## Configure budgets

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

export default defineUnlighthouseConfig({
  site: 'https://staging.example.com',
  ci: {
    reporter: 'json',
    budget: { performance: 80, accessibility: 90 },
    buildStatic: true,
  },
})
```

Run `pnpm exec unlighthouse-ci` to use the configured site and budget.
Budgets use percentages from 1 to 100.

## Reports

| Reporter               | Export                                           |
| ---------------------- | ------------------------------------------------ |
| `json` or `jsonSimple` | `ci-result.json`                                 |
| `jsonExpanded`         | `ci-result.json`, with reconciled report details |
| `csv` or `csvSimple`   | `ci-result.csv`                                  |
| `csvExpanded`          | `ci-result.csv`, with configured audit columns   |
| `false`                | No result export; budgets still apply            |

Exports live under the configured output directory.
An explicit `--reporter` overrides `ci.reporter`.
Use `ci.reporterConfig.columns` for expanded CSV column arrays.

## Devices and cache

```sh
pnpm exec unlighthouse-ci --site https://example.com --device mobile,desktop --no-cache --reporter csv
```

JSON rows include `device`; CSV adds a final `Device` column.
Treat `(path, device)` as the row identity.
Read CSV columns by their header name.
CI follows configured cache behavior. Use `--no-cache` to reset output.

## Static dashboard

Use `--build-static` to generate a static dashboard after the scan.
Publish the complete generated client directory so assets remain available.

## Lighthouse CI server

Install the optional Lighthouse CI utilities before uploading raw Lighthouse results:

```sh
pnpm add -D @lhci/utils
pnpm exec unlighthouse-ci --site https://example.com --reporter lighthouseServer --lhci-host https://lhci.example.com --lhci-build-token "$LHCI_TOKEN"
```

Keep the build token in your runner secrets.
For previous CI integrations, read [Migrating to v1](/guide/guides/migrating-to-v1).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.