Integrating Lighthouse Score into Your CI/CD Pipeline with GitHub Actions - A Complete Guide

Published: at 08:00 AM

Introduction

In the world of web development, delivering performant, accessible, and SEO-friendly websites is a top priority. Google’s Lighthouse tool is a powerful utility that helps developers ensure their web apps are up to the highest standards by providing actionable insights into performance, accessibility, best practices, and search engine optimization (SEO).

However, running Lighthouse manually each time you make a change to your code can be cumbersome. Integrating Lighthouse into your Continuous Integration/Continuous Deployment (CI/CD) pipeline, specifically using GitHub Actions, allows you to automate this process. This automation helps you catch performance and accessibility regressions early in the development cycle, improving the quality of your web application.

In this comprehensive guide, we will walk through how to integrate Lighthouse audits into your CI/CD pipeline using GitHub Actions. We’ll cover everything from setting up GitHub Actions, configuring Lighthouse, customizing performance thresholds, and handling test failures.

Table of Contents

Open Table of Contents

1. What is Lighthouse?

Lighthouse is an open-source tool developed by Google for auditing the quality of web pages. It assesses multiple facets of a web page, such as:

•Performance: Measures load speed, rendering efficiency, and overall user experience.

•Accessibility: Ensures that the page is accessible to users with disabilities.

•Best Practices: Follows web development best practices like using HTTPS, avoiding deprecated APIs, etc.

•SEO: Provides recommendations to improve search engine visibility.

•Progressive Web App (PWA): Checks if your web app is following PWA standards.

Lighthouse generates a score from 0 to 100 for each of these categories, providing detailed reports and suggestions for improvement.

2. Why Integrate Lighthouse into CI/CD Pipelines?

Incorporating Lighthouse into your CI/CD pipeline helps ensure that your web application maintains high-quality standards as you develop. Here are the main benefits:

•Continuous Monitoring: Automate performance, accessibility, and SEO checks on every commit or pull request.

•Catch Regressions Early: Prevent performance issues and accessibility problems from going unnoticed.

•Enforce Quality Standards: Define performance thresholds and enforce them through automated testing.

•Seamless Workflow: Leverage GitHub Actions to run Lighthouse audits without manual intervention.

By integrating Lighthouse into your pipeline, you streamline the development process while maintaining a high level of quality for your web application.

3. What is GitHub Actions?

GitHub Actions is a CI/CD platform built into GitHub, which allows developers to automate workflows based on events like pull requests, commits, or scheduled intervals. With GitHub Actions, you can define custom workflows using YAML files to run your code through various stages of testing, build, and deployment.

Some key benefits of using GitHub Actions are:

•Native to GitHub: Seamlessly integrates with your GitHub repositories.

•Custom Workflows: Define automated processes using YAML files.

•Flexible Triggers: Trigger workflows on specific events like pull requests, pushes, or schedule-based triggers.

•Extensive Marketplace: Leverage a marketplace of pre-built actions to extend your CI/CD pipeline.

In this tutorial, we will use GitHub Actions to automate Lighthouse audits.

4. Setting Up Your GitHub Repository

Before we start writing the GitHub Actions workflow, we need a repository to work with. If you don’t have one yet, follow these steps to set up your repository:

4.1. Create a GitHub Repository

1.Go to your GitHub dashboard.

2.Click on the “New Repository” button.

3.Name your repository (e.g., lighthouse-ci-demo), choose visibility (public or private), and click “Create repository”.

4.2. Clone the Repository Locally

git clone https://github.com/<your-username>/<repository-name>.git
cd <repository-name>

4.3. Add a Basic Web Application

<!-- index.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Lighthouse CI Demo" />
    <title>Lighthouse CI Demo</title>
  </head>
  <body>
    <h1>Welcome to Lighthouse CI Demo</h1>
  </body>
</html>

Commit and push the changes to your GitHub repository.

git add .
git commit -m "Add basic web page"
git push origin main

Now that we have our web application, let’s proceed to the next step—creating a GitHub Action to run Lighthouse audits.

5. Creating a GitHub Action for Lighthouse

To run Lighthouse audits in GitHub Actions, we need to define a workflow. A workflow is a YAML file that describes the series of steps to be executed when a certain event (e.g., a push to the main branch) occurs.

5.1. Create a Workflow Directory

Inside your repository, create a .github/workflows directory to store the workflow YAML file:

mkdir -p .github/workflows

5.2. Write the GitHub Action Workflow

Create a file called lighthouse.yml inside .github/workflows and add the following code:

# .github/workflows/lighthouse.yml

name: Lighthouse CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  lighthouse:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Install Node.js
        uses: actions/setup-node@v2
        with:
          node-version: "22"

      - name: Install Lighthouse CI
        run: |
          npm install -g @lhci/cli

      - name: Run Lighthouse CI
        run: |
          lhci autorun

5.3. Explanation of the Workflow

6. Customizing Your Lighthouse CI Configuration

The lhci autorun command we used above requires configuration. Let’s create a lighthouserc.js file in the root of the project to customize the behavior of Lighthouse CI.

6.1. Create a Lighthouse Configuration File

In the root of your repository, create a new file called lighthouserc.js with the following content:

// lighthouserc.js

module.exports = {
  ci: {
    collect: {
      url: ["http://localhost:8080"], // Change to your deployed URL
      startServerCommand: "npm start", // Starts your web server
      numberOfRuns: 3, // Run Lighthouse audits multiple times
    },
    assert: {
      preset: "lighthouse:recommended", // Recommended performance thresholds
    },
    upload: {
      target: "temporary-public-storage",
    },
  },
};

6.2. Explanation of Configuration

Commit and push your changes to the repository.

git add lighthouserc.js
git commit -m "Add Lighthouse CI configuration"
git push origin main

7. Handling Failures and Setting Thresholds

You can configure Lighthouse CI to fail the pipeline if certain performance or accessibility thresholds are not met. This is especially useful for enforcing quality standards across your web application.

7.1. Custom Thresholds

In the lighthouserc.js configuration, you can set custom thresholds using the assert key:

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      /* ... */
    },
    assert: {
      assertions: {
        "categories:performance": ["error", { minScore: 0.9 }], // Minimum 90% performance
        "categories:accessibility": ["error", { minScore: 0.95 }], // Minimum 95% accessibility
        "categories:seo": ["error", { minScore: 0.85 }], // Minimum 85% SEO
      },
    },
    upload: {
      /* ... */
    },
  },
};

Here’s what each assertion means:

If your web app doesn’t meet these thresholds, the pipeline will fail, preventing poor-quality code from being merged.

7.2. Failures in the CI/CD Pipeline

If the Lighthouse scores fall below your specified thresholds, GitHub Actions will automatically fail the job, and you’ll see an error message in the pull request.

In this case, you will need to address the issues raised by Lighthouse before you can proceed with the merge.

8. Generating Reports and Artifacts

Lighthouse CI generates detailed HTML reports that help you visualize performance metrics. GitHub Actions can store these reports as artifacts so that you can download and view them later.

8.1. Modify GitHub Action to Store Artifacts

Update your lighthouse.yml workflow file to include artifact storage:

# .github/workflows/lighthouse.yml
name: Lighthouse CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  lighthouse:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Install Node.js
        uses: actions/setup-node@v2
        with:
          node-version: "22"

      - name: Install Lighthouse CI
        run: |
          npm install -g @lhci/cli

      - name: Run Lighthouse CI
        run: |
          lhci autorun

      - name: Upload Lighthouse Report
        uses: actions/upload-artifact@v2
        with:
          name: lighthouse-report
          path: "./.lighthouseci/*"

8.2. Explanation of Artifact Storage

Upload Lighthouse Report: This step uses the actions/upload-artifact action to upload the Lighthouse reports generated in the .lighthouseci directory. These artifacts will be available for download directly from the GitHub Actions UI.

Once the pipeline completes, you’ll see a download link for the Lighthouse report in the GitHub Actions interface.

9. Visualizing Lighthouse Data with GitHub Action Results

Beyond the HTML report, you can surface Lighthouse scores directly in the GitHub Actions summary. For this, you can use the @foo-software/lighthouse-check-action to generate a more visual summary in your CI/CD pipeline.

9.1. Add Lighthouse Check Action

Update your lighthouse.yml to use the Lighthouse Check Action:

# .github/workflows/lighthouse.yml

name: Lighthouse CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  lighthouse:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Install Node.js
        uses: actions/setup-node@v2
        with:
          node-version: "22"

      - name: Install Lighthouse CI
        run: |
          npm install -g @lhci/cli

      - name: Run Lighthouse CI
        run: |
          lhci autorun

      - name: Generate Lighthouse Summary
        uses: foo-software/lighthouse-check-action@master
        with:
          urls: "http://localhost:8080"
          outputDirectory: "./lighthouse-reports"

This action will generate a summary of the Lighthouse scores directly in the GitHub Actions results.

9.2. Explanation of the Action

Generate Lighthouse Summary: This step uses the foo-software/lighthouse-check-action to run Lighthouse audits and surface the results in the GitHub Actions output.

The summary includes performance, accessibility, SEO, and best practices scores, making it easier to review Lighthouse results directly in the GitHub UI.

10. Best Practices and Advanced Techniques

When integrating Lighthouse into your CI/CD pipeline, there are several advanced techniques you can adopt to make the process even more effective:

10.1. Parallel Testing for Multiple Pages

If your web application has multiple pages, you can run Lighthouse audits in parallel for different URLs.

collect:
  { url: ["http://localhost:8080/page1", "http://localhost:8080/page2", ...] }

10.2. Scheduled Lighthouse Audits

You can schedule Lighthouse audits to run periodically to catch regressions in performance or SEO even if no code changes are made.

on:
  schedule:
    - cron: "0 0 * * 1" # Runs every Monday at midnight

10.3. Integrate with Slack or Other Communication Tools

Send Lighthouse results to Slack or other communication channels to alert your team when the pipeline fails due to performance regressions.

11. Conclusion

By integrating Lighthouse audits into your GitHub Actions pipeline, you ensure that every commit meets the necessary performance, accessibility, SEO, and best practice standards. This automated process helps prevent regressions, improves overall quality, and fosters a culture of continuous improvement in web development.

You’ve now learned how to:

With this setup, you’ll be able to keep your web application optimized and user-friendly, all while maintaining a seamless development workflow. Happy coding!