Lighthouse Automated Testing and Reporting with GitHub Actions and


Ever noticed those snazzy badges on GitHub repositories showcasing website performance metrics and wished you could have them for your own site? Not only do they look cool, but they also offer a quick glance into the health of a project. In this article, I’ll unravel the magic behind automating Lighthouse reports and effortlessly integrating them into your README page using GitHub Actions, Gists, and

You can see a working example for this website here:

Lighthouse performance badge Lighthouse accessibility badge Lighthouse best-practices badge Lighthouse SEO badge


What is Lighthouse?

Lighthouse is a free, open-source, and automated tool from Google that helps developers improve the quality of web pages. It provides a comprehensive report on various parameters like performance, accessibility, SEO, best practices, and more. Think of it as an audit for your website – Lighthouse will highlight what we’re doing right and where there’s room for improvement. Read more about Lighthouse.

Lighthouse Report Image

What are status badges and

You know those fancy little badges you see on some GitHub repos indicating build status, coverage percentage, or other metrics? Those are status badges! They provide a visual representation of specific metrics and serve as a quick way to understand a repo’s status. Enter - a service that allows you to create custom badges for practically anything, including Lighthouse metrics. Badges Image


If we want to have status badges for Lighthouse metrics on our GitHub README page we need multiple things:

  • Run Lighthouse report on every new change
  • Generate report with metrics we are interested in
  • Have our badges display the latest data

One option would be to commit a change to our own repository every time to update the badges with the new data. While this works it is kind of messy and pollutes our commit history with a lot of automated extra commits. So we need a clean way to do this without changing the README file every time which means the badges need to get their data dynamically from somewhere.


My solution for this challenge? GitHub Gists. Gists are like lightweight repos made for sharing code snippets and such. We can use one to publish our report and have our badges read data from it. We will leverage the endpoint badge for this. So the process now looks like this:

  1. Run Lighthouse in GitHub Actions
  2. Generate report files
  3. Publish report files to a gist
  4. Create endpoint badges

1. Running Lighthouse in GitHub Actions

Setting up GitHub Actions to run Lighthouse automatically pretty straightforward. You could use an already made action from the marketplace, I prefer to use the CLI directly and avoid the dependency. Here is a snippet of the workflow that runs the test:

name: CI/CD
      - main
    runs-on: ubuntu-latest
    needs: deploy
      - name: Install Node.js v18
        uses: actions/setup-node@v4
          node-version: 18
      - name: Install Lighthouse CI
        run: npm install -g @lhci/cli@0.12.x
      - name: Run Lighthouse
        run: |
          lhci autorun --collect.numberOfRuns=5 --collect.url=${{github.run_id}} --upload.outputDir=./reports/mobile
          lhci autorun --collect.numberOfRuns=5 --collect.url=${{github.run_id}} --upload.outputDir=./reports/desktop --collect.settings.preset=desktop
  • The lighthouse job needs deploy so it will run after the deployment is completed
  • There are three steps, first we install node, then we install the lighthouse cli and finally we execute the lighthouse commands
  • I use --collect.numberOfRuns=5 to execute the test 5 times to get a reliable result.
  • I just target the landing page but you target any pages you want.
  • I add ?v=${{github.run_id}} to avoid caching issues to ensure the last version is tested.
  • Lastly you can use --collect.settings.preset=desktop to test the desktop version, otherwise it will test as mobile.

You can find the full YAML file for this website here.

2. Generate Lighthouse report with powershell

Now, to make the Lighthouse results usable by the endpoint badge, we need to generate a JSON file. The schema is:

{ "schemaVersion": 1, "label": "hello", "message": "sweet world", "color": "orange" }

We already have the test results available from the previous step, we only need to process them to generate what we need. For this we will use a custom powershell script. We’ll execute it right after the lighthouse test in our job:

      - name: Generate Lighthouse report
        shell: pwsh
        run: .\.github\actions\lighthouse-report.ps1
          LIGHTHOUSE_PATH_MOBILE: ./reports/mobile
          LIGHTHOUSE_PATH_DESKTOP: ./reports/desktop

We can use the following snippet to generate the JSON files:

$manifest_desktop = Get-Content -Path (Join-Path -Path $reports_desktop -ChildPath "manifest.json") | ConvertFrom-Json

# Get data for summary
foreach($run in $manifest_desktop){
    $performance = $run.summary.performance * 100;
    $accessibility = $run.summary.accessibility * 100;
    $bestPractices = $run.summary.'best-practices' * 100;
    $seo = $run.summary.seo * 100;
    $report = $run.htmlPath;

# Creates a JSON badge file for
function WriteBadgeFile ([string] $label, [string] $message, [string] $color, [string] $file)
  $content = ("
   `"schemaVersion`": 1,
   `"label`": `"$($label)`",
   `"message`": `"$($message)`",
   `"color`": `"$($color)`"
  new-item -force -path (Join-Path -Path $output_dir -ChildPath $file) -value $content -type file

# Generate all output files
WriteBadgeFile "Performance" $performance (GetScoreColor $performance) "performance.json"
WriteBadgeFile "Accessibility"  $accessibility (GetScoreColor $accessibility) "accessibility.json"
WriteBadgeFile "Best-practices"  $bestPractices (GetScoreColor $bestPractices) "best_practices.json"
WriteBadgeFile "SEO" $seo (GetScoreColor $seo) "seo.json"

Now we have a JSON file for each badge we want to create in our ./summary folder. We are ready to publish them so the data is available to our badges.

You can check the full script I use here (keep in mind I’m doing some other things like printing the results in the GitHub actions step summary).

3. Using Gist to publish Lighthouse results

Gists are an easy way to share snippets of code or data. We’ll use them to host our Lighthouse result JSON files. Here is how you can push the report files to a gist.

  • Create a gist here and take note of the ID
  • Set up an access token so your job is allowed to push to your gist
  • Add a final step to the job to push the files to the gist (I use a custom powershell script for this)
      - name: Publish reports to gist
        shell: pwsh
          UPDATE_GIST_TOKEN: ${{ secrets.GISTS_ACCESS_TOKEN }}
          UPDATE_GIST_ID: 3f8ee5d85053832ea374a05b301f57aa
          UPDATE_GIST_PATH: summary
        run: .\.github\actions\update-gist.ps1

You can find my update-gist script here

4. Create badges

Here comes the fun part!

  • Head over to and choose the endpoint badge type.
  • For the URL, input the URL of the Gist containing your Lighthouse JSON result.
  • Customize the badge appearance as you see fit.
  • Embed the badge in your README. Now, every time Lighthouse runs and updates the Gist, your badge will reflect the new results!


Lighthouse performance badge Lighthouse accessibility badge Lighthouse best-practices badge Lighthouse SEO badge


If you push the full HTML report from lighthouse to you gist too then you make the report available like this. You just need to get the raw HTML and pass it to<USER>/<GIST_ID>/raw/report.html


That’s it! With these steps, you’ve got an automated Lighthouse testing setup with nifty badges showcasing your website’s performance. It’s a little bragging, a little quality assurance, and a whole lot of geeky fun. Enjoy!