Skip to main content

How to add Lighthouse to a continuous integration system, like GitHub Actions.

It appears in:
Fast loading times

CI headlight is a set of tools to use Lighthouse during continuous integration. Lighthouse CI can be incorporated into developer workflows in many different ways. This guide covers the following topics:

  • Using the Lighthouse CI CLI.
  • Configuring your CI provider to run Lighthouse CI.
  • Set up a GitHub action and
    status check
    for Lighthouse CI. This will automatically show Lighthouse results in GitHub pull requests.
  • Create a performance dashboard and data warehouse for Lighthouse reports.


Lighthouse CI is a set of free tools that make it easy to use Lighthouse for performance monitoring. A single Lighthouse report provides a snapshot of the performance of a web page as it runs; Lighthouse CI shows how these findings have changed over time. This can be used to identify the impact of particular code changes or to ensure that performance thresholds are met during continuous integration processes. Although performance monitoring is the most common use case for Lighthouse CI, it can be used to monitor other aspects of the Lighthouse report, for example SEO or accessibility.

The primary functionality of Lighthouse CI is provided by the Lighthouse CI command line interface. (Note: this is a separate tool from the Lighthouse CLI.) The Lighthouse CI CLI provides a set of
to use Lighthouse CI. For example, him autorun The command runs multiple Lighthouse runs, identifies the Medium Lighthouse report, and loads the report for storage. This behavior can be highly customized by passing additional flags or by customizing the Lighthouse CI configuration file, lighthouserc.js.

Although the core functionality of Lighthouse CI is primarily encapsulated in the Lighthouse CI CLI, Lighthouse CI is typically used through one of the following approaches:

  • Running Lighthouse CI as part of continuous integration
  • Using a Lighthouse CI GitHub action that runs and comments on every pull request
  • Track performance over time through the dashboard provided by Lighthouse Server.

All of these approaches are based on the Lighthouse CI CLI.

Alternatives to Lighthouse CI include third-party performance monitoring services or writing your own script to collect performance data during the CI process. You should consider using a third-party service if you prefer to let someone else take care of managing your performance monitoring server and test devices, or if you want notification capabilities (such as email or Slack integration) without having to create them. features yourself.

Use Lighthouse CI locally

This section explains how to run and install the Lighthouse CI CLI locally and how to configure lighthouserc.js. Running the Lighthouse CI CLI locally is the easiest way to ensure that your lighthouserc.js is configured correctly.

  1. Install the Lighthouse CI CLI.

    npm install -g @ lhci / cli

    Lighthouse CI is configured by placing a lighthouserc.js file in the root of your project repository. This file is required and will contain configuration information related to Lighthouse CI. Although Lighthouse CI can configured to be used without a git repository, the instructions in this article assume that your project repository is configured to use git.

  2. In the root of your repository, create a lighthouserc.js configuration file.

    touch lighthouserc.js

  3. Add the following code to lighthouserc.js. This code is an empty Lighthouse CI configuration. You will add to this configuration in later steps.

    module . exports = {
    ci : {
    collect : {
    } ,
    upload : {
    } ,
    } ,
    } ;

  4. Every time Lighthouse CI runs, it starts a server to serve your site. This server is what allows Lighthouse to load your site even when there are no other servers running. When Lighthouse CI finishes running, it will automatically shut down the server. To make sure the publication works correctly, you must configure the



    If your site is static, add the staticDistDir property to ci.collect
    object to indicate where your static files are located. Lighthouse CI will use its own server to serve these files while you test your site. If your site is not static, add the startServerCommand property to
    ci.collect object to indicate the command that starts your server. Lighthouse CI will start a new server process during the test and shut it down afterwards.

    collect : {
    staticDistDir : './public' ,

    collect : {
    startServerCommand : 'npm run start' ,

  5. Add the

    property to ci.collect object to indicate URL (s) where Lighthouse CI should run Lighthouse. The value of the url the property must be provided as a URL array; this array can contain one or more URLs. By default, Lighthouse CI will run Lighthouse three times on each URL.

    collect : {
    url : [ 'http: // localhost: 8080' ]

    Note: The server you configured in the previous step should be able to publish these URLs. So if you are running Lighthouse CI locally these URLs should probably include localhost instead of your production host.

  6. Add the

    property to ci.upload object and set the value to
    'temporary-public-storage'. The Lighthouse reports collected by Lighthouese CI will be uploaded to temporary public storage. The report will stay there for seven days and then it will be automatically deleted. This configuration guide uses the "temporary public storage" upload option because it is quick to configure. For information on other ways to store Lighthouse reports, see the

    upload : {
    target : 'temporary-public-storage' ,

    The report storage location will look like this:

    (This URL will not work because the report has already been removed.)

  7. Run the Lighthouse CI CLI from the terminal using the autorun command. This will run Lighthouse three times and load the Medium Lighthouse report.

    lhci autorun

    If you have successfully configured Lighthouse CI, running this command should produce output similar to this:

    ✅ .lighthouseci / directory writable
    ✅ Configuration file found
    ✅ Chrome installation found
    ⚠️ GitHub token not set
    Healthcheck passed !

    Started a web server on port 65324 ...
    Running Lighthouse 3 time ( s ) on http: // localhost: 65324 / index.html
    Donate running Lighthouse !

    Uploading via LHR of http: // localhost: 65324 / index.html .. .success !
    Open the report at
    No GitHub token set, skipping GitHub status check.

    Donate running autorun.

    You can ignore the GitHub token not set message in the console output. A GitHub token is only required if you want to use Lighthouse CI with a GitHub action. How to configure a GitHub action is explained later in this article.

    By clicking the link in the output that begins with
    https: // ... will take you to the Lighthouse report for Lighthouse's medium run.

    The default values used by autorun can be overridden via command line or
    lighthouserc.js. For example, him lighthouserc.js The following configuration indicates that five Lighthouse executions should be collected at a time autorun

  8. To update lighthouserc.js use the numberOfRuns property:

    module . exports = {
    collect : {
    numberOfRuns : 5
    } ,
    } ,
    } ;

  9. Run the autorun command:

    lhci autorun

    The terminal output should show that Lighthouse has been run five times instead of the default three:

    ✅ .lighthouseci / directory writable
    ✅ Configuration file found
    ✅ Chrome installation found
    ⚠️ GitHub token not set
    Healthcheck passed !

    Automatically Determined ./dist as `` staticDistDir.
    Set it explicitly in lighthouserc.json if incorrect.

    Started a web server on port 64444 ...
    Running Lighthouse 5 time ( s ) on http: // localhost: 64444 / index.html
    Donate running Lighthouse !

    Uploading via LHR of http: // localhost: 64444 / index.html .. .success !
    Open the report at
    No GitHub token set, skipping GitHub status check.

    Donate running autorun.

    For other configuration options, see Lighthouse CI
    setup documentation.

Configure your CI process to run Lighthouse CI

Lighthouse CI can be used with your favorite CI tool. the Configure your CI provider
The Lighthouse CI documentation section contains code samples showing how to incorporate Lighthouse CI into common CI tools configuration files. Specifically, these code samples show how to run Lighthouse CI to collect performance metrics during the CI process.

Using Lighthouse CI to collect performance metrics is a good place to start with performance monitoring. However, advanced users may want to go one step further and use Lighthouse CI to fail builds if they don't meet predefined criteria, such as passing specific Lighthouse audits or meeting all performance budgets. This behavior is configured through the

property of the lighthouserc.js proceedings.

Lighthouse CI supports three levels of assertions:

  • off: ignore assertions
  • warn: print faults in stderr
  • error- Print faults to stderr and exit Lighthouse CI with a non-zero value
    exit code

Below is an example of lighthouserc.js configuration that includes assertions. Set claims for Lighthouse performance and accessibility category scores. To test this, add the affirmations shown below to your lighthouserc.js and then run Lighthouse CI again.

module . exports = {
ci : {
collect : {
} ,
assert : {
assertions : {
'categories: performance' : [ 'warn' , { minScore : 1 } ] ,
'categories: accessibility' : [ 'error' , { minScore : 1 } ]
} ,
upload : {
} ,
} ,
} ;

The console output it generates looks like this:


For more information on the claims of Lighthouse CI, see the

Configure a GitHub Action to Run Lighthouse CI

This section assumes that you are familiar with git, GitHub, and GitHub pull requests.

A GitHub action can be used to run Lighthouse CI. This will generate a new Lighthouse report every time a code change is pushed to any branch in a GitHub repository. Use this in conjunction with a status check
to display these results on every pull request.

  1. At the root of your repository, create a directory called
    .github / workflows. the
    for your project it will go in this directory. A workflow is a process that runs at a predetermined time (for example, when code is submitted) and is made up of one or more actions.

    mkdir .github
    mkdir .github / workflows

  2. In .github / workflows create a file called lighthouse-ci.yaml. This file will contain the settings for a new workflow.

    touch lighthouse-ci.yaml

  3. Add the following text to lighthouse-ci.yaml.

    name : Build project and run Lighthouse CI
    on : [ push ]
    jobs :
    lhci :
    name : Lighthouse CI
    runs-on : ubuntu - latest
    steps :
    - uses : actions / checkout @ v1
    - name : Use Node.js 10.x
    uses : actions / setup - node @ v1
    with :
    node-version : 10.x
    - name : npm install
    run : |
    npm install

    - name : run Lighthouse CI
    run : |
    npm install -g @ lhci / cli @ 0.3.x
    lhci autorun = temporary-public-storage || echo "LHCI failed!"

    This configuration establishes a workflow consisting of a single job that will run each time new code is submitted to the repository. This job has four steps:

    • Check the repository where Lighthouse CI will run
    • Install and configure Node
    • Install the required npm packages
    • Run Lighthouse CI and upload the results to temporary public storage.
  4. Commit these changes and submit them to GitHub. If you have followed the steps above correctly, submitting code to GitHub will trigger the execution of the workflow you just added.

  5. To confirm that Lighthouse CI has been activated and view the report it generated, go to Behavior tab of your project. You should see the
    Build project and run Lighthouse CI workflow listed in your most recent commit.


    You can navigate to the Lighthouse report for a particular commit from the Behavior tongue. Click the commitment, click the CI headlight
    step of the workflow, then expand the results of the run Lighthouse CI He passed.


    You have just configured a GitHub action to run Lighthouse CI. This will be most useful when used in conjunction with a GitHub status check.

Set up a GitHub health check

A health check, if configured, is a message that appears on every RP and typically includes information such as the results of a test or the success of a build.


The following steps explain how to configure a health check for Lighthouse CI.

  1. Go to the Lighthouse CI GitHub App Page and click Set up.

  2. (Optional) If you are part of multiple organizations on GitHub, choose the organization that owns the repository for which you want to use Lighthouse CI.

  3. Please select All repositories if you want to enable Lighthouse CI in all repositories or select Select only repositories if you only want to use it on specific repositories, and then select the repositories. Then click
    Install and authorize.

  4. Copy the token that is displayed. You will use it in the next step.

  5. To add the token, navigate to Configurations page of your GitHub repository, click Mysteries, then click Add a new secret.

  6. Select the Name field to LHCI_GITHUB_APP_TOKEN and configure the Value
    field to the token you copied in the last step and then click the Add secret button.

  7. The health check is ready to use. To prove it, create a new pull request
    or send a confirmation to an existing pull request.

Configure the Lighthouse CI Server

The Lighthouse CI server provides a dashboard to explore the Lighthouse historical reports. It can also act as a long-term private data warehouse for Lighthouse reports.

  1. Choose which commitments to compare.
  2. The amount that Lighthouse's score changed between the two commits.
  3. This section only shows the metrics that have changed between the two commits.
  4. Regressions are highlighted in pink.
  5. Improvements are highlighted in blue.

Lighthouse CI Server is best suited for users who are comfortable implementing and managing their own infrastructure.

For information on how to configure the Lighthouse CI server, including recipes for using Heroku and Docker for deployment, see these

Know more

R Marketing Digital