Web Performance Optimization & Lighthouse · Lesson

Integrating Lighthouse into CI/CD

Automate Lighthouse checks within your continuous integration and deployment pipelines to catch performance regressions early.

Integrating Lighthouse into CI/CD is a free Web Performance Optimization & Lighthouse lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Web Performance Optimization & Lighthouse learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What is CI/CD?

CI/CD stands for Continuous Integration and Continuous Delivery/Deployment. It's a modern approach to software development that focuses on automating various stages of the software lifecycle.

Continuous Integration (CI): Developers frequently merge code into a central repository. Automated builds and tests run to detect issues early.
Continuous Delivery (CD): After CI, code is automatically prepared for release, ensuring it's always in a deployable state.
Continuous Deployment (CD): Takes CD a step further by automatically deploying every change to production, provided all tests pass.

CI/CD helps teams deliver updates faster and more reliably.

Why CI/CD for Performance?

Integrating performance checks into your CI/CD pipeline is crucial for maintaining a fast website. Here's why:

Catch Regressions Early: Automatically detect performance drops with every code change, before they reach users.
Consistent Feedback: Get objective performance scores on every build, ensuring teams stay aware of their impact.
Enforce Standards: Use performance budgets to fail builds if metrics fall below acceptable thresholds.
Save Time: Automate manual auditing, freeing up developer time.

Meet Lighthouse CI (LHCI)

While you can run Lighthouse manually, Lighthouse CI (LHCI) is a dedicated tool designed to make automated performance auditing in CI/CD pipelines easy and effective.

LHCI provides a set of tools to:

Collect Lighthouse reports across different branches and commits.
Assert performance budgets against these reports.
Display historical performance data.
Integrate with various CI providers like GitHub Actions, GitLab CI, and Jenkins.

LHCI: Collect & Assert

LHCI works through a command-line interface (CLI). You'll typically use two main commands:

lhci collect: Runs Lighthouse audits on specified URLs and collects the results.
lhci assert: Checks the collected results against predefined performance budgets and rules.

First, you usually install it globally or as a dev dependency:

npm install -g @lhci/cli

Configuring LHCI

LHCI uses a configuration file, often named lighthouserc.js or lighthouserc.json, to define how it should run. This file lives at the root of your project.

Here's a basic structure for lighthouserc.js, specifying where to run audits:

module.exports = {
  ci: {
    collect: {
      url: ['http://localhost:3000'],
      startServerCommand: 'npm run start',
      numberOfRuns: 3,
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

Enforcing Performance Budgets

A key feature of LHCI is enforcing performance budgets. These are thresholds for metrics (like score, total byte weight, or largest contentful paint) that your site must meet.

You define budgets in the assert section of your lighthouserc.js. If any budget is violated, LHCI can fail your CI build.

module.exports = {
  ci: {
    collect: { /* ... */ },
    assert: {
      assertions: {
        'performance-score': ['error', { minScore: 0.90 }],
        'first-contentful-paint': ['error', { maxNumericValue: 1500 }],
        'total-byte-weight': ['warn', { maxNumericValue: 1000000 }], // 1MB
      },
    },
    upload: { /* ... */ },
  },
};

LHCI with GitHub Actions

GitHub Actions is a popular CI/CD platform integrated directly into GitHub repositories. You can easily add LHCI to your GitHub Actions workflow.

You'll create a YAML file (e.g., .github/workflows/lighthouse.yml) that defines the steps to run LHCI when certain events occur, like a pull request or a push to the main branch.

This allows automated checks before merging code.

GitHub Actions Workflow Example

Here's a simplified GitHub Actions workflow that sets up Node.js, installs LHCI, starts a server (if needed), collects audits, and asserts against budgets.

This workflow runs on every pull request to the main branch.

name: Lighthouse CI
on: [pull_request]
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install dependencies
        run: npm ci
      - name: Run Lighthouse CI
        run: npm install -g @lhci/cli && lhci collect && lhci assert

Reviewing CI/CD Results

After LHCI runs in your CI/CD pipeline, it provides output directly in the build log. If budgets are set, the build will pass or fail accordingly.

Passed: All performance budgets and assertions were met.
Failed: One or more budgets were exceeded, indicating a performance regression.

For more detailed historical data and trend analysis, you can configure LHCI to upload reports to an LHCI server (either self-hosted or a cloud service).

Quick Check

You've learned how Lighthouse CI helps automate performance checks. Which of the following are key benefits of integrating Lighthouse CI into your CI/CD pipeline?

Recap & Next Steps

Great job! In this lesson, we explored how to integrate Lighthouse into your CI/CD pipeline.

We understood the importance of automating performance checks to prevent regressions.
We learned about Lighthouse CI (LHCI) and its role in collecting audits and asserting budgets.
We saw examples of configuring LHCI and integrating it with GitHub Actions.

By automating performance, you ensure your web projects remain fast and user-friendly over time. Keep exploring how to fine-tune your CI/CD setup for optimal results!

Frequently asked questions

Is the “Integrating Lighthouse into CI/CD” lesson free?

Yes — the full text of “Integrating Lighthouse into CI/CD” is free to read here on the web, and the Web Performance Optimization & Lighthouse course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Web Performance Optimization & Lighthouse course, upgrade to CoddyKit PRO.

What will I learn in “Integrating Lighthouse into CI/CD”?

Automate Lighthouse checks within your continuous integration and deployment pipelines to catch performance regressions early. You practise Web Performance Optimization & Lighthouse with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Web Performance Optimization & Lighthouse?

No prior experience is required. Web Performance Optimization & Lighthouse on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Integrating Lighthouse into CI/CD” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Web Performance Optimization & Lighthouse lesson?

Yes. Every Web Performance Optimization & Lighthouse lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Web Performance Optimization & Lighthouse