‘Google Lighthouse logo’

In this tutorial, we’re going to run a Lighthouse audit every time Tugboat builds out a Preview of our website. If the build is coming from a Pull Request, we’ll also update the deployment status, and post a comment back to the issue with the score results.

Lighthouse is an open-source, automated tool for improving the quality of web pages. It performs audits for performance, accessibility, progressive web apps, and more. This tool is usually run from within the Chrome browser, but it can also be run as a Node module or from the command line. That kind of flexibility makes Lighthouse a perfect tool for automation. The reports that Lighthouse generates look like this (use a Chrome browser):

Lighthouse Report Viewer 2018 09 17 14 22 53

At the time of this writing that link is best viewed in Chrome and does not work in Safari. The bug has been fixed but not yet deployed.

And if you want to jump to the end of this tutorial, here’s the full Tugboat config file to automate Lighthouse. Most of the Lighthouse-related process is in the build command of the PHP service.

Add Your Repository to Tugboat

The first step is to connect a GitHub repository to Tugboat and have a Tugboat configuration file building out your Previews. If you don’t have a Repository you’d like to use, go ahead and fork the one we’re using. This will build a working Backdrop CMS site for you.

Create a Personal Access Token

For Tugboat to set the Pull Request status and post the JSON version of the report as a Gist, we need a Personal Access Token.

The permissions scope for your Personal Access Token should include at the least the following:

Personal Access Token 2018 09 07 10 50 23

Gist access allows Tugboat to upload a JSON format of the report so Google Lighthouse Viewer can access it.

After you create your Personal Access Token, add it to Tugboat as a Custom Environment Variable. You can get there by clicking on the settings link for your Repository. When you add the environment variable it will look similar this:


If you use GITHUB_TOKEN as the variable name, you won’t need to change this config file. Don’t forget to hit the Save button.

Add your Tugboat SSH Key to GitHub

Adding your SSH Key as a Deploy Key to GitHub will let Tugboat post a comment back to the Pull Request issue. You can grab a copy of your Tugboat SSH public key on the Repository settings page.

Tugboat Ssh Key 2018 09 17 14 38 21

Once the key has been added to your Repository settings on Github, it will look similar to this:

Deploy Keys 2018 09 07 11 11 34

Update your Tugboat Config File

If you’re using a forked version of our repository, be sure to run a Pull Request against the lighthouse branch, which contains the full config file for Lighthouse integration. If you’re using a different repository, here’s a paired-down version of a Tugboat config file showing only the Lighthouse-related commands for you to integrate.

Test it

If all goes well, you’ll now see a comment in your pull request to viewing the Lighthouse results! If not, check out the log files in Tugboat (on the Preview page for your build) and look for clues.

Lighthouse Integration Pull Request 2018 09 11 17 21 43

If you have any questions or concerns, stop by our Slack channel and say hello. We’d love to hear from you!