Concepts

Key terms and how they fit together.

Core models

Page Definition — A URL you want to audit, along with its name, schedule, and configuration. Every audit starts from a page definition.

Build — A single audit run request. A build is created when an audit is triggered (manually, on schedule, or via the API). Each build targets one page definition.

Run — The actual Lighthouse execution within a build. Contains the raw performance data and scores.

Statistic — Individual metrics extracted from a run (e.g. Largest Contentful Paint, Total Blocking Time). Statistics are what power the trend charts on your dashboard.

Score — The 0–100 Lighthouse score for each category: Performance, Accessibility, Best Practices, and SEO.

Credits — Each audit consumes one credit from your account's allocation. Credits reset on your billing cycle.

Audit lifecycle

Every audit moves through a predictable set of states:

  1. Scheduled — The build is queued and waiting to be picked up
  2. Running — Lighthouse is actively auditing the page
  3. Succeeded — The audit completed and results are available
  4. Failed — Something went wrong (page unreachable, timeout, etc.)

Failed audits still consume a credit. Make sure your URL is reachable and responds within a reasonable time before scheduling recurring audits.

Scheduling

Page definitions can be set to run on a recurring schedule:

  • Hourly — good for high-traffic production pages where you need rapid regression detection
  • Daily — the default; balances coverage with credit usage
  • Weekly — for lower-priority pages or when credits are limited

Authenticated pages

If your page requires authentication (e.g. a logged-in dashboard), you can provide cookies or custom headers in the page definition. Xcelera will include these credentials when running Lighthouse so the audit sees the authenticated version of the page.

Auth credentials are stored encrypted but treat them as sensitive. Use short-lived tokens or session cookies where possible.

GitHub integration

Xcelera can integrate with GitHub to automatically audit pages on every pull request.

Setup

  1. Install the Xcelera GitHub App on your repository
  2. Connect the repository to your Xcelera account in Settings → Connections
  3. Xcelera will create a check run on each PR with the audit results

How it works

When a PR is opened or updated, Xcelera triggers an audit using the API with the PR's commit information. The results appear as a GitHub check run, showing whether performance regressed compared to the baseline.

Help