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):
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:
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:
GITHUB_TOKEN=LAgMBAAECgYAQg3IDbucmXohLo4GT9iYCrQDOwyo
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.
Once the key has been added to your Repository settings on Github, it will look similar to this:
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.
If you have any questions or concerns, stop by our Slack channel and say hello. We’d love to hear from you!