Lighthouse GitHub Actions: Automated SEO and Performance Monitoring

Quick Summary

- What this covers: Automate Lighthouse audits with GitHub Actions to catch SEO and performance regressions before deployment. Learn setup, configuration, and alert workflows.

- Who it's for: SEO practitioners at every career stage

- Key takeaway: Read the first section for the core framework, then use the specific tactics that match your situation.

• Why Automate Lighthouse Audits
• Setting Up Lighthouse GitHub Actions
• SEO-Focused Lighthouse Configuration
• Core Web Vitals Tracking
• Handling Dynamic and Authenticated Pages
• Alerting on Regressions
• Example: Full Lighthouse GitHub Actions Workflow
• When This Approach Isn't Right

Lighthouse audits web pages for performance, accessibility, SEO, and best practices. Running Lighthouse manually before every deploy doesn't scale. GitHub Actions automates Lighthouse audits on every pull request, catching regressions before they reach production.

This guide shows how to integrate Lighthouse with GitHub Actions, configure SEO-focused audits, and set up alerting for performance and SEO issues.

Why Automate Lighthouse Audits

Manual Lighthouse audits face three problems:

Inconsistency: Developers forget to run audits, or only audit on desktop, or skip audits when rushing to deploy. Late detection: Discovering a performance regression after deployment means rollback complexity, angry users, and lost rankings. No historical tracking: Manual audits produce one-time scores with no trend data to identify gradual degradation. Automated Lighthouse via GitHub Actions solves these: Consistency: Every pull request runs audits automatically, no human memory required. Early detection: Regressions get caught during code review, before merging to main. Failed audits block merges. Historical tracking: Store audit results in artifacts or external services to track performance trends over time. SEO-specific use cases:

• Catch meta tag removals or canonical tag errors before deployment
• Detect structured data breakage or schema.org validation errors
• Monitor crawlability issues (broken internal links, robots.txt changes)
• Track Core Web Vitals trends (LCP, CLS, FID) across releases

Setting Up Lighthouse GitHub Actions

Basic Workflow Configuration

Create a GitHub Actions workflow file at .github/workflows/lighthouse.yml:

``yaml

name: Lighthouse CI

on:

pull_request:

branches:

- main

jobs:

lighthouse:

runs-on: ubuntu-latest

steps:

- name: Checkout code

uses: actions/checkout@v3

- name: Install Node.js

uses: actions/setup-node@v3

with:

node-version: '18'

- name: Install dependencies

run: npm install

- name: Build site

run: npm run build

- name: Run Lighthouse

uses: treosh/lighthouse-ci-action@v9

with:

urls: |

https://example.com

https://example.com/blog

https://example.com/products

uploadArtifacts: true

temporaryPublicStorage: true

` What this does:

Triggers on pull requests to main

Checks out code

Installs dependencies and builds the site

Runs Lighthouse against specified URLs

Uploads audit results as artifacts

URL targeting: Test critical pages—homepage, top landing pages, key product pages. Auditing 5-10 pages catches most issues.

Lighthouse CI Server Setup (Advanced)

For persistent storage and historical trends, use Lighthouse CI Server.

Benefits:

• Stores audit history across all branches and PRs
• Provides web UI for comparing runs
• Enables trend analysis (performance over time)
• Supports assertions (fail builds if scores drop below thresholds)

Setup:

Deploy Lighthouse CI Server (Heroku, Vercel, or self-hosted Docker container)

Update workflow to post results to the server:

`yaml

• name: Run Lighthouse CI

uses: treosh/lighthouse-ci-action@v9

with:

urls: |

https://example.com

https://example.com/blog

serverBaseUrl: https://your-lhci-server.herokuapp.com

serverToken: ${{ secrets.LHCISERVERTOKEN }}

`

Add assertions in a lighthouserc.json config:

`json

{

"ci": {

"collect": {

"numberOfRuns": 3

},

"assert": {

"assertions": {

"categories:performance": ["error", {"minScore": 0.9}],

"categories:seo": ["error", {"minScore": 0.95}],

"categories:accessibility": ["warn", {"minScore": 0.9}]

}

},

"upload": {

"target": "lhci",

"serverBaseUrl": "https://your-lhci-server.herokuapp.com",

"token": "YOUR_TOKEN"

}

}

}

` Assertions:

• categories:performance requires performance score ≥90
• categories:seo requires SEO score ≥95
• categories:accessibility warns if accessibility <90 but doesn't fail

Pull requests that fail assertions get blocked from merging.

SEO-Focused Lighthouse Configuration

Lighthouse's SEO audit checks 16+ factors. Customize which failures block deployments.

SEO Audit Categories

Lighthouse SEO audits include:

Document structure: