Lighthouse CI Configuration & Storage #

Establish deterministic CI gating, persistent result storage, and automated threshold enforcement to eliminate performance regression drift. This configuration framework transforms subjective audits into enforceable engineering standards. By integrating Lighthouse CI & WebPageTest Integration into your deployment pipeline, teams automate budget validation and block suboptimal code before it reaches production.

Configuration Architecture & File Formats #

Select the appropriate configuration format based on your environment injection requirements. Use lighthouserc.json for static, version-controlled baselines that guarantee reproducibility across all environments. Opt for lighthouserc.js when you require dynamic environment variable resolution, conditional routing logic, or runtime URL generation from CI context.

Standard JSON configuration block:

{
 "ci": {
 "collect": {
 "url": ["https://staging.example.com/", "https://staging.example.com/checkout"],
 "numberOfRuns": 3,
 "settings": {
 "preset": "desktop",
 "chromeFlags": "--no-sandbox --disable-dev-shm-usage"
 }
 }
 }
}

Map sensitive credentials and dynamic endpoints via environment variables to avoid hardcoding:

• LHCI_TOKEN: Authentication token for the centralized LHCI server.
• LHCI_SERVER_BASE_URL: Endpoint for the persistent storage backend.
• LHCI_BUILD_CONTEXT__CURRENT_HASH: Git SHA for precise historical correlation.

Override configuration at runtime using CLI flags when pipeline parameters shift:

lhci autorun --config=./config/lighthouserc.json --collect.url=https://pr-123.builds.example.com

Storage Backend Selection & Implementation #

Choose a storage target that aligns with your retention requirements, query volume, and compliance standards. The filesystem backend suits ephemeral local testing. The LHCI server (backed by SQLite or PostgreSQL) provides centralized dashboards, API access, and historical trend visualization. For enterprise-scale analytics, route artifacts to BigQuery or object storage (S3/GCS) via custom upload scripts.

Configure the upload target in your lighthouserc file:

{
 "ci": {
 "upload": {
 "target": "lhci",
 "serverBaseUrl": "${LHCI_SERVER_BASE_URL}",
 "token": "${LHCI_TOKEN}"
 }
 }
}

Implement strict data retention policies to prevent storage bloat. Configure automated pruning to delete runs older than 30 days or retain only the latest 50 builds per branch. When scaling to high-frequency CI runs, pair LHCI with a WebPageTest Private Instance Setup to distribute load and maintain consistent metric baselines across isolated network environments.

Performance Budgets & Assertion Thresholds #

Enforce quantitative limits using the ci.assert block. Assertions fail the CI pipeline immediately when thresholds are breached, preventing budget degradation.

{
 "ci": {
 "assert": {
 "assertions": {
 "categories:performance": ["error", { "minScore": 0.90 }],
 "metric-lcp": ["error", { "maxNumericValue": 2500 }],
 "metric-cls": ["error", { "maxNumericValue": 0.1 }],
 "metric-fcp": ["warn", { "maxNumericValue": 1500 }],
 "metric-tbt": ["error", { "maxNumericValue": 200 }],
 "resource-summary:document:size": ["error", { "maxNumericValue": 15000 }],
 "resource-summary:script:size": ["error", { "maxNumericValue": 200000 }]
 },
 "preset": "lighthouse:recommended",
 "includePassedAssertions": true
 }
 }
}

Mitigate flaky environments by implementing fallback logic. Use dynamic routing to bypass assertions on known unstable staging routes. Differentiate mobile vs. desktop profiles by injecting distinct configuration files based on pipeline matrix variables. Enable ci.assert.retain to preserve historical baseline data, allowing regression detection even when absolute thresholds temporarily shift due to third-party script updates or CDN routing changes.

CI Pipeline Integration & Execution Flow #

Integrate Lighthouse CI directly into your GitHub Actions workflow. The following job definition ensures deterministic execution, strict timeout controls, and proper artifact handling.

name: Performance Gating
on:
 pull_request:
 branches: [main, develop]

jobs:
 lighthouse-ci:
 runs-on: ubuntu-latest
 timeout-minutes: 15
 concurrency:
 group: ${{ github.workflow }}-${{ github.ref }}
 cancel-in-progress: true
 steps:
 - uses: actions/checkout@v4
 - uses: actions/setup-node@v4
 with:
 node-version: '20'
 - run: npm ci
 - run: npm run build
 - name: Run Lighthouse CI
 run: npx lhci autorun
 env:
 LHCI_TOKEN: ${{ secrets.LHCI_TOKEN }}
 LHCI_SERVER_BASE_URL: ${{ secrets.LHCI_SERVER_BASE_URL }}
 # Map LHCI exit codes to pipeline status: 0=pass, 1=assertion failure, 2=fatal error
 continue-on-error: false
 - name: Upload Artifacts
 if: always()
 uses: actions/upload-artifact@v4
 with:
 name: lighthouse-reports
 path: .lighthouseci/

Scale execution across multiple environments and viewport configurations by leveraging GitHub Actions Performance Matrices to run parallel audit jobs without blocking the main pipeline. Configure branch protection rules to require the lighthouse-ci status check to pass before merging. For detailed PR gating implementation, refer to Running Lighthouse CI on Every Pull Request.

Storage Optimization & Troubleshooting #

Address common pipeline failures systematically. Timeout errors typically stem from unoptimized asset delivery or unresponsive staging environments. Increase timeout-minutes and verify network routing. Storage quota limits require automated pruning scripts and retention policy enforcement. Assertion drift occurs when third-party dependencies update; pin dependency versions or implement dynamic baseline adjustments. Headless Chrome crashes in CI are resolved by adding --no-sandbox and --disable-dev-shm-usage to chromeFlags.

Execute targeted debugging commands:

• lhci healthcheck: Validates environment variables, Chrome availability, and server connectivity.
• lhci collect --verbose: Outputs raw Lighthouse JSON and network request traces.
• Parse assertion mismatch logs by filtering for LHCI_ASSERTION_FAILED to isolate exact metric breaches.

Stabilize results through deterministic execution:

• Warm caches by running a preliminary curl or wget request before lhci collect.
• Target exact, versioned URLs rather than dynamic redirects.
• Override default network throttling with --collect.settings.throttlingMethod=provided and explicit --collect.settings.throttling.cpuSlowdownMultiplier=1 for consistent CI environments.

Pre-Deployment Validation Checklist

• [ ] Lint configuration: npx lhci healthcheck --fatal
• [ ] Audit thresholds: Verify minScore and maxNumericValue against current production baselines
• [ ] Verify storage backup: Confirm retention policies and quota alerts are active
• [ ] Dry-run pipeline: Execute workflow on a feature branch with --upload.target=filesystem before enabling server uploads and PR gating