Catching SEO Regressions with Lighthouse CI

Manual audits catch problems after they ship; the goal of a mature workflow is to catch them before merge. Lighthouse CI runs Lighthouse against a preview build on every pull request and fails the check when the SEO or performance score drops below a budget — turning indexability into a gate rather than a periodic review. It is the automation layer of the SPA audit workflow and the cheapest possible place to catch a rendering regression.

Step-by-step fix

  1. Add Lighthouse CI to the pipeline. Run it against a preview URL for each pull request so every change is measured before it merges.

    # .github/workflows/lhci.yml
- run: npm run build && npm run preview &
- run: npx @lhci/cli autorun --collect.url=http://localhost:4173/products/widget-x

  2. Assert on SEO and performance budgets. Configure assertions so a regression fails the build instead of silently lowering the score.

    // lighthouserc.js
module.exports = {
  ci: {
    assert: {
      assertions: {
        'categories:seo':         ['error', { minScore: 0.95 }],
        'categories:performance':  ['warn',  { minScore: 0.80 }],
        'document-title':          'error',  // fails if <title> missing
        'meta-description':        'error',  // fails if description missing
      },
    },
  },
};

  3. Make the check required. In branch protection, mark the Lighthouse CI status as required so a regression cannot be merged.

    ❌ Lighthouse runs but is advisory → regressions merge anyway
✅ Lighthouse status is required   → SEO score drop blocks the merge

  4. Test the templates that matter. Point the collector at one URL per template (product, article, listing), not just the homepage, so template-level regressions are caught.

Validation

  • A pull request that removes the <title> fails the document-title assertion.
  • The SEO category stays at or above your minScore on every merge.
  • The check is required and visibly blocks merges when it fails.
  • Trend reports (LHCI server or uploaded artifacts) show scores stable or improving over time.

Reference 

// Minimal lighthouserc.js for SEO gating across templates
module.exports = {
  ci: {
    collect: {
      url: [
        'http://localhost:4173/',
        'http://localhost:4173/products/widget-x',
        'http://localhost:4173/blog/example-post',
      ],
    },
    assert: {
      assertions: {
        'categories:seo': ['error', { minScore: 0.95 }],
        'document-title': 'error',
        'meta-description': 'error',
        'crawlable-anchors': 'error',  // SEO: links must be crawlable <a href>
      },
    },
  },
};

Frequently Asked Questions

Can Lighthouse catch rendering problems in a CI pipeline? Yes. Lighthouse renders the page in headless Chromium and reports the SEO category, including whether the document has a title, meta description, and crawlable content. Asserting on those audits in CI fails the build when a change strips metadata or breaks rendering.

Should Lighthouse CI run on the production URL or a preview? Run it against a per-pull-request preview deployment so regressions are caught before merge. Running only against production catches problems after they have already shipped and possibly been crawled.

← Back to SEO Audit Workflows for Client-Side Apps