Github Action for Lighthouse
Tags: performance, softwaredelivery, development
Published: 2020-02-12 04:41:14

---
title: Github Action for Lighthouse
published: true
date: 2020-02-05 14:12:19 UTC
tags: performance,software delivery,development
canonical_url: https://mattorb.com/github-action-for-lighthouse/
---

 ![Github Action for Lighthouse](https://mattorb.com/content/images/2020/02/james-wheeler-@souvenirpixels-InOgamK2cuY-unsplash.jpg) photo credit: [james-wheeler](https://unsplash.com/@souvenirpixels)

After using a [Github action to assess web page performance with Google PageSpeed](https://mattorb.com/github-action-for-google-pagespeed-insights/), I found out that [PageSpeed leverages a tool called Lighthouse](https://bit.ly/lhpsi5) for most of what it now provides.  When I was configuring a [Github action to check for Javascript library security vulnerabilities](https://mattorb.com/github-action-for-javascript-vulnerability-scan/), I remember it using a package called Lighthouse, too.

🤔

According to Google, the [Lighthouse project](https://github.com/GoogleChrome/lighthouse) provides . . .

> "Automated auditing, performance metrics, and best practices for the web"

NOTE: This is the same suite of tests that execute when you launch Google Chrome and use the audits tab in Developer Tools, and the same suite of tests that now provide a large portion of what is reported back by Google PageSpeed.

Some quick scouting on Github revealed some existing efforts focused around [making Lighthouse easier to plug in to CI/CD](https://github.com/andreasonny83/lighthouse-ci) and [packaging it into a Github Action](https://github.com/treosh/lighthouse-ci-action).

For the purpose of asserting and maintaining a baseline performance level on [this site](https://mattorb.com/), we're going to try leveraging the [Lighthouse Github Action](https://github.com/treosh/lighthouse-ci-action).   Thanks to Aleksey and the contributors!

## The Github Action

First step: add a workflow file _.github/workflows/lighthouse.yml_ in the Github repository which should trigger Lighthouse:

<!--kg-card-begin: markdown-->
```
name: Lighthouse
on: 
  push:
    branches:
    - master
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Audit URLs using Lighthouse
        uses: treosh/lighthouse-ci-action@v2
        with:
          urls: 'https://mattorb.com/'
      - name: Save results
        uses: actions/upload-artifact@v1
        with:
          name: lighthouse-results
          path: '.lighthouseci'

```
<!--kg-card-end: markdown-->

After committing that workflow file, it executes, and we can go grab the artifact generated by lighthouse and see what our scores look like.  

![Github Action for Lighthouse](https://mattorb.com/content/images/2020/02/Screen-Shot-2020-02-04-at-8.32.18-AM.png)<figcaption>Find Github action artifacts here</figcaption>

That zip file contains both a json and html representation of the report.

Inspecting the summary portion of the html report gives us overall scores in various areas and provides much more detail below that fold:

![Github Action for Lighthouse](https://mattorb.com/content/images/2020/02/Screen-Shot-2020-02-04-at-8.28.11-AM.png)<figcaption>Lighthouse scoring areas, summary. For breakdown and recommendations, see full report.</figcaption>

Based on those numbers, decide where to _draw the line_ and set a threshold to not fall below in each of the categories.  Leave some room for variability in server performance though.  Nobody wants to be dealing with false alerts regularly.

Create a _.github/lighthouse/lighthouserc.json_ file in the repository with Lighthouse assertions you want to enforce:

<!--kg-card-begin: markdown-->
```
{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", {"minScore": 0.90}],
        "categories:accessibility": ["error", {"minScore": 0.80}],
        "categories:best-practices": ["error", {"minScore": 0.92}],
        "categories:seo": ["error", {"minScore": 0.90}]
      }
    }
  }
}

```
<!--kg-card-end: markdown-->

Configure the stanza in the Github Action at _.github/workflows/lighthouse.yml_ to enact those assertions by pointing it to that config file:

<!--kg-card-begin: markdown-->
```
✂️ 

    steps:
      - uses: actions/checkout@v1
      - name: Audit URLs using Lighthouse
        uses: treosh/lighthouse-ci-action@v2
        with:
          urls: 'https://mattorb.com/'
          configPath: '.github/lighthouse/lighthouserc.json' # Assertions config file 

✂️ 

```
<!--kg-card-end: markdown-->

Next time the action executes, it will check that we don't drop below these thresholds.  

If one of those assertions fails, it will fail the workflow with a message:

![Github Action for Lighthouse](https://mattorb.com/content/images/2020/02/Screen-Shot-2020-02-04-at-8.45.18-AM.png)<figcaption>Failing to meet the performance criteria</figcaption>

You can fail the workflow based on overall scores or make even finer grained assertions using items called out in the detail of the report.  Check out the [Lighthouse CI documentation on assertions](https://github.com/GoogleChrome/lighthouse-ci/blob/master/docs/assertions.md) for examples.

## Going Further

- Run a [Lighthouse CI server](https://github.com/GoogleChrome/lighthouse-ci) to provide tracking of these metrics over time in a purpose built solution for that.
- Use multiple runs to average out server performance and draw more manageable thresholds.  
- Use the concept of a [page performance budget](https://web.dev/use-lighthouse-for-performance-budgets/) to set guide-rails and limits around size and quantity of external (think .js and .css) resources.
- Shift left and assess a site change while it is still in the PR stage 
- Design specific test suites and set unique performance/seo requirements based on what kind of page is being probed.
- Leverage a [Lighthouse plugin](https://github.com/ampproject/amp-toolbox/tree/master/packages/lighthouse-plugin-amp) to assess pages that have opinionated and strict design requirements for their target platforms (i.e. - [AMP](https://en.wikipedia.org/wiki/Accelerated_Mobile_Pages)).