CircleCI is a popular tool for orchestrating CI/CD pipelines. Lighthouse is an open-source project from Google for improving the quality of web pages. It provides user-centric metrics to audit SEO, performance, accessibility, best practices, and progressive web apps.

For a deeper dive about Lighthouse you can read “How to analyze website performance with Lighthouse”.

By combining these forces, we can establish website quality automation. This post will demonstrate the following:

• Basic implementation of Lighthouse in a CircleCI workflow.
• Advanced setup to display Lighthouse results in pull request comments.
• S3 Lighthouse report uploads.
• Slack notifications.

Lighthouse Check CircleCI Orb

CircleCI Orbs are shareable packages of configuration elements, including jobs, commands, and executors you use in your workflows. This post will provide a guide for using the Lighthouse Check CircleCI Orb for automating Lighthouse audits.

Basic Example

Below is a minimal example and all we need to run Lighthouse automatically on any code change ? In this example both https://www.foo.software and https://www.foo.software/contact will be audited.

version: 2.1

orbs:
  lighthouse-check: foo-software/lighthouse-check@0.0.8

jobs:
  test: 
    executor: lighthouse-check/default
    steps:
      - lighthouse-check/audit:
          urls: https://www.foo.software,https://www.foo.software/contact

workflows:
  test:
    jobs:
      - test

With this minimal setup we have a summary provided in the output of our job. We also have full HTML reports saved as CircleCI "artifacts".

Advanced Example

Lighthouse Check CircleCI Orb offers a complete set of bells and whistles by utilizing lighthouse-check NPM module under the hood. There’s so much more we can do with this. Let’s proceed!

Pull Request Comments

By utilizing this feature, comments are posted with Lighthouse results on every commit. We can do so by following the steps below.

1. Create a new user or find an existing one to act as a “bot”.
2. Create a personal access token from this user account.
3. Create a CircleCI environment variable in your project to hold the encrypted value from above. In our example we name it LIGHTHOUSE_CHECK_GITHUB_ACCESS_TOKEN.
4. Update our config file with the diff shown below.

+ prCommentAccessToken: $LIGHTHOUSE_CHECK_GITHUB_ACCESS_TOKEN
+ prCommentUrl: https://api.github.com/repos/foo-software/lighthouse-check-orb/pulls/${CIRCLE_PULL_REQUEST##*/}/reviews
urls: https://www.foo.software,https://www.foo.software/contact

The updates above provides a token to authorize comments on a corresponding pull request. prCommentUrl should be an endpoint in the format specified by the GitHub API. Your endpoint will be similar but with owner and repo params replaced ( foo-software/lighthouse-check-orb ). With this, we’ve created a bot to post Lighthouse results on pull requests ?

S3 Report Uploads

In our example we persist results by uploading reports as artifacts in our job. This solution could be sufficient in some cases, but artifacts aren’t stored permanently. In order to view reports, we need to navigate into the workflow and manually download reports from the artifact view.

But what if we want a more dependable way of storing and referencing reports? This is where the S3 feature comes into play. We can configure AWS S3 storage by following the below steps.

1. Create an AWS account if you don’t already have one.
2. Create an S3 bucket if you don’t already have one.
3. Acquire an AWS access key id and secret access key.
4. Create a CircleCI environment variables for these two values. In our example we’ll use LIGHTHOUSE_CHECK_AWS_ACCESS_KEY_ID and LIGHTHOUSE_CHECK_AWS_SECRET_ACCESS_KEY, respectively.
5. Add the bucket name and region (example: us-east-1) as CircleCI environment variables: LIGHTHOUSE_CHECK_AWS_BUCKET and LIGHTHOUSE_CHECK_AWS_REGION.

Next, we’ll update our configuration with the following diff.

+ awsAccessKeyId: $LIGHTHOUSE_CHECK_AWS_ACCESS_KEY_ID
+ awsBucket: $LIGHTHOUSE_CHECK_AWS_BUCKET
+ awsRegion: $LIGHTHOUSE_CHECK_AWS_REGION
+ awsSecretAccessKey: $LIGHTHOUSE_CHECK_AWS_SECRET_ACCESS_KEY
prCommentUrl: https://api.github.com/repos/foo-software/lighthouse-check-orb/pulls/${CIRCLE_PULL_REQUEST##*/}/reviews

In our next commit and push, reports are automatically uploaded to S3 ✅! We also have a them linked in our PR comments.

Slack Notifications

What’s a new feature in a DevOps workflow without Slack notifications? A sad one indeed. Let’s ramp things up by adding notifications to a Slack channel for our whole team to see. We can accomplish this in the below steps.

1. Create an “Incoming Webhook” in your Slack workspace and authorize a channel.
2. Add the Webhook URL as a CircleCI environment variable — LIGHTHOUSE_CHECK_SLACK_WEBHOOK_URL.

+ slackWebhookUrl: $LIGHTHOUSE_CHECK_SLACK_WEBHOOK_URL
urls: https://www.foo.software,https://www.foo.software/contact

Our next commit and push introduces Slack notifications! The “Lighthouse audit” link in the below screenshot navigates to the S3 report as configured ✨

At this point our complete "advanced example" configuration looks like the below.

usage:
  version: 2.1

  orbs:
    lighthouse-check: foo-software/lighthouse-check@0.0.8

  jobs:
    test: 
      executor: lighthouse-check/default
      steps:
        - lighthouse-check/audit:
            awsAccessKeyId: $LIGHTHOUSE_CHECK_AWS_ACCESS_KEY_ID
            awsBucket: $LIGHTHOUSE_CHECK_AWS_BUCKET
            awsRegion: $LIGHTHOUSE_CHECK_AWS_REGION
            awsSecretAccessKey: $LIGHTHOUSE_CHECK_AWS_SECRET_ACCESS_KEY
            prCommentAccessToken: $LIGHTHOUSE_CHECK_GITHUB_ACCESS_TOKEN
            prCommentUrl: https://api.github.com/repos/foo-software/lighthouse-check-orb/pulls/${CIRCLE_PULL_REQUEST##*/}/reviews
            slackWebhookUrl: $LIGHTHOUSE_CHECK_SLACK_WEBHOOK_URL
            urls: https://www.foo.software,https://www.foo.software/contact

  workflows:
    test:
      jobs:
        - test

Maintaining a Historical Record

Foo’s Automated Lighthouse Check is tool we can use to manage a historical record of Lighthouse audits. We can connect to it with the Lighthouse Check Orb! By doing so you can run Lighthouse remotely versus in a local, dockerized CircleCI environment. With this we can be assured our Lighthouse results aren't flaky from CircleCI infrastructure change. Follow the documented steps to connect with Automated Lighthouse Check.

What Now?

You can find other of examples of Lighthouse Check Orb usage on GitHub. I hope this article has provided a helpful addition to your DevOps workflow! With Lighthouse integrated in a CI/CD pipeline, we can stay fully equipped to ensure high quality in website SEO, performance, accessibility, best practice, and progressive web apps.