Lighthouse CI Accessibility Integration
What Is Lighthouse CI?
Lighthouse CI is a suite of tools for running Google Lighthouse audits in CI pipelines. The most common GitHub Actions integration uses
treosh/lighthouse-ci-action
.
Lighthouse provides:
- Performance, accessibility, best practices, and SEO scoring (0-100)
- Individual audit results with pass/fail status and detailed findings
- Score budgets and assertions to fail builds on regressions
- HTML and JSON report artifacts
- Score comparison across runs for trend tracking
Accessibility focus: The Lighthouse accessibility category runs a subset of axe-core rules and reports a weighted score from 0-100 along with individual audit violations.
Detecting Lighthouse CI Presence
Workflow File Detection
Search for workflow files referencing Lighthouse CI:
bash
# Search for the treosh Lighthouse CI action
grep -rl "treosh/lighthouse-ci-action" .github/workflows/
# Search for official Lighthouse CI CLI usage
grep -rl "lhci autorun\|lighthouse-ci" .github/workflows/
Patterns to match in YAML:
yaml
- uses: treosh/lighthouse-ci-action@v12
Configuration File Detection
Lighthouse CI uses configuration files in the repository root:
bash
# Check for Lighthouse CI config files
ls lighthouserc.js lighthouserc.json .lighthouserc.js .lighthouserc.json .lighthouserc.yml 2>/dev/null
| Config File | Format |
|---|
| JavaScript module |
| JSON |
| JavaScript module (dotfile) |
| JSON (dotfile) |
| YAML (dotfile) |
Configuration Structure
Key fields in Lighthouse CI config:
json
{
"ci": {
"collect": {
"url": ["https://example.com", "https://example.com/about"],
"numberOfRuns": 3
},
"assert": {
"assertions": {
"categories:accessibility": ["error", {"minScore": 0.9}]
}
},
"upload": {
"target": "temporary-public-storage"
}
}
}
| Section | Purpose | Agent Use |
|---|
| URLs to audit | Scope of CI scanning |
| How many times to run each URL | Reliability indicator |
| Score budgets and thresholds | Regression detection |
| Where to store reports | Report retrieval |
Parsing Lighthouse Accessibility Results
Accessibility Score
Lighthouse computes a weighted accessibility score from 0-100 based on individual audit results.
| Score Range | Grade | Interpretation |
|---|
| 90-100 | A | Good accessibility |
| 70-89 | B-C | Some issues to address |
| 50-69 | D | Significant issues |
| 0-49 | F | Critical accessibility failures |
Individual Audit Results
Each Lighthouse accessibility audit corresponds to an axe-core rule:
| Audit ID | axe-core Rule | WCAG Criterion | Weight |
|---|
| | 1.1.1 | 10 |
| | 1.4.3 | 7 |
| | 1.3.1 | 7 |
| | 4.1.2 | 7 |
| | 2.4.4 | 7 |
| | 3.1.1 | 7 |
| | 2.4.2 | 7 |
| | 1.3.1 | 3 |
| | 1.4.4 | 10 |
| | 2.4.1 | 7 |
| | 2.4.3 | 7 |
| | 4.1.2 | 10 |
| | 4.1.2 | 10 |
| | 4.1.2 | 10 |
| | 4.1.2 | 7 |
| | 4.1.2 | 7 |
| | 4.1.2 | 10 |
Severity Mapping
Lighthouse uses weights rather than impact levels. Map to the agent severity model based on weight and audit pass/fail:
| Lighthouse Weight | Audit Status | Agent Severity |
|---|
| 10 | Fail | Critical |
| 7 | Fail | Serious |
| 3 | Fail | Moderate |
| 1 | Fail | Minor |
| Any | Pass | N/A (not reported) |
Correlation with Local Scans
Lighthouse-to-axe-core Mapping
Since Lighthouse uses axe-core under the hood, correlation is straightforward:
- Match by audit/rule ID: Lighthouse audit IDs correspond directly to axe-core rule IDs
- Match by URL: Compare scanned URLs from Lighthouse config with local scan targets
- Boost confidence: Findings confirmed by both Lighthouse CI and local axe-core scan receive confidence
Source Comparison
| Scenario | Interpretation | Action |
|---|
| Found by Lighthouse AND local scan | High confidence | Report as high confidence, full severity weight |
| Found by Lighthouse only | Environment-specific | Report as medium confidence, note "CI-only finding" |
| Found by local scan only | Not covered by Lighthouse subset | Report as medium confidence, note "local-only finding" |
| Lighthouse score regressed | New accessibility issues introduced | Flag as regression, prioritize in report |
Score Regression Detection
Track Lighthouse accessibility scores across runs to detect regressions:
Comparing Scores
json
{
"url": "https://example.com",
"previousScore": 95,
"currentScore": 87,
"delta": -8,
"status": "regressed",
"newFailures": ["color-contrast", "image-alt"],
"newPasses": []
}
Regression Thresholds
| Delta | Severity | Action |
|---|
| Score drops 10+ points | Critical | Immediate attention, likely multiple new violations |
| Score drops 5-9 points | Serious | New violations introduced, review before merge |
| Score drops 1-4 points | Moderate | Minor regression, track for follow-up |
| Score unchanged or improved | N/A | No regression detected |
Structured Output Format
When
normalizes Lighthouse data, it produces findings in this format:
json
{
"source": "lighthouse-ci",
"ruleId": "color-contrast",
"wcagCriterion": "1.4.3",
"wcagLevel": "AA",
"severity": "serious",
"confidence": "high",
"url": "https://example.com/login",
"element": "button.submit-btn",
"description": "Element has insufficient color contrast ratio",
"lighthouseWeight": 7,
"lighthouseScore": {
"overall": 87,
"previousOverall": 95,
"delta": -8,
"status": "regressed"
}
}
GitHub Actions Integration
treosh/lighthouse-ci-action
The most common Lighthouse CI GitHub Action:
yaml
- name: Run Lighthouse CI
uses: treosh/lighthouse-ci-action@v12
with:
urls: |
https://example.com
https://example.com/about
uploadArtifacts: true
configPath: ./lighthouserc.json
Action Inputs
| Input | Required | Description |
|---|
| Yes (or in config) | Newline-separated URLs to audit |
| No | Path to Lighthouse CI config file |
| No | Upload HTML reports as workflow artifacts |
| No | Upload to temporary public storage for sharing |
| No | Number of runs per URL (default: 1) |
| No | Path to a Lighthouse budget JSON file |
Extracting Results from Artifacts
Lighthouse CI uploads results as workflow artifacts. To retrieve scores:
- Download the artifact from the workflow run
- Parse the JSON report files
- Extract
categories.accessibility.score
- Extract individual results for violations