Self-hosted Lighthouse CI
Lighthouse scores for every repo, on one server you run
Register a repo, add one CI step, and every pull request uploads its Lighthouse report to your LHCI server. The score history lives in your own Postgres database.
- 91Performance
- 100Accessibility
- 96Best Practices
- 92SEO
| Commit | Branch | Perf |
|---|---|---|
| 3f9c2e1 | feature/hero-image | 91 |
| b71d0a4 | main | 87 |
| 0e5a9c3 | main | 84 |
Sample data. Compared against base branch main.
One server, three small tools
- 01
LHCI server
The upstream @lhci/server, configured to store every build in Postgres and to gate every route with one server-wide basicAuth pair.
- 02
lhci-toolkit
A CLI with two commands: register a repo as a project and print its build token, or list the projects on the server.
- 03
Login helpers
Puppeteer helpers that sign in before Lighthouse audits a page: credential login, session injection and app basic auth.
- 04
lhci-onboarding skill
A Claude Code skill that walks a repo through registration, its lighthouserc.js upload config and the CI step.
What the server and toolkit do
- 01
Score history in Postgres
Every uploaded Build and its Runs are stored in a Postgres database you own, so trends survive redeploys.
- 02
One gate for every route
Server basicAuth protects the dashboard, registration and the upload endpoint with one username and password.
- 03
Registration with two tokens
lhci-toolkit register creates a Project and prints its Build token for CI and an Admin token you keep.
- 04
Uploads from any CI pipeline
Run npx @lhci/cli autorun with three secrets and each pull request uploads its report.
- 05
Own-build and Live audits
Audit the app your CI builds, the URL you already deployed, or both, without the uploads colliding.
- 06
PSI collection for Client sites
For sites with no CI pipeline, the server runs scheduled PageSpeed Insights audits itself.
- 07
Build retention
A daily job deletes Builds and their Runs older than 30 days, or the age you set.
- 08
Audits behind a login
Login helpers sign Lighthouse’s browser in before it audits a dashboard or account page.
- 09
Self-hosted, in one container
The server is plain JavaScript in one container image, configured only by environment variables.
From a new repo to scores on every pull request
- Step 1
Deploy the server
Run apps/server as a container with a Postgres database and set LHCI_DATABASE_URL and the server basicAuth pair, LHCI_BASIC_AUTH_USERNAME and LHCI_BASIC_AUTH_PASSWORD.
- Step 2
Register the repo
lhci-toolkit register <name> creates a Project and prints its id, its Build token and its Admin token. Registration itself needs the server basicAuth pair.
- Step 3
Wire lighthouserc.js
Point upload at your server with target lhci, the Build token and upload.basicAuth. Without basicAuth the upload fails with 401, even with a valid token.
- Step 4
Add the CI step
Run npx @lhci/cli autorun with LHCI_BUILD_TOKEN, LHCI_BASIC_AUTH_USERNAME and LHCI_BASIC_AUTH_PASSWORD. Add GITHUB_TOKEN and Lighthouse CI posts its score on the pull request.
Keep your score history in one place you own
Deploy the server once, then onboard each repo in a few minutes.