Shopify Lighthouse CI GitHub Action

Optimizing your theme for performance is key to the success of the merchants that you support, and the experience of their customers. It directly influences conversion rates, repeat business, and search engine rankings.

Every change you make to your theme code can have an impact on performance. To make sure that you identify code that is slowing down your theme before it is in production, you can integrate Lighthouse tests into your theme development workflow using the Shopify Lighthouse CI GitHub Action.

The Shopify Lighthouse CI GitHub Action is a Shopify-specific GitHub Action based off of Google's Lighthouse CI. It runs a Lighthouse audit as part of your continuous integration process for every pull request that you create. It tests the performance of your theme's home page, a product page, and a collection page.

To install the Shopify Lighthouse CI GitHub Action for themes, you must do the following:

  1. Add private app credentials for the store that you want to use for testing to GitHub.
  2. Create a new GitHub Action workflow for the Shopify Lighthouse CI GitHub Action.
  3. Optional: if you want to see the status of your Lighthouse CI run in the GitHub UI, then add Lighthouse CI as a GitHub status check.

Requirements

  • A development store - You should create a development store that is dedicated to running Lighthouse CI and manual performance tests.
  • Performance-specific store data - To get consistent results from Lighthouse, you should populate your store using the test product csv. The store should have no other collections, products, or variants. This file contains the same data that is used to test themes before they are accepted into the Shopify Theme Store.
  • API credentials for the development store - Lighthouse CI uses private app credentials to connect to your store. Enable private app development on the store, then create a new private app.

    The app needs to have the Read and write Themes permission, and the Read access Product permission. You'll need the API key and password for the private app that you create.

1. Add your private app credentials to GitHub

In your theme's GitHub repo, add the following information as environment secrets:

  • SHOP_APP_ID - Your private app's API key
  • SHOP_APP_PASSWORD- Your private app's password
  • SHOP_STORE - Your development store's myshopify.com URL, in the format your-store-name.myshopify.com.
  • SHOP_PASSWORD - The password for your development store. If you don't provide this value, then Lighthouse is redirected to the password page and will not accurately test your theme's performance.

2. Create a new GitHub Action workflow

  1. Create a new GitHub Action workflow file that runs shopify/lighthouse-ci-action (for example, at .github/workflows/lighthouse-ci.yml):

  2. Commit this code and create a pull request. You should see a GitHub Action that runs Lighthouse on your pull request’s code.

3. Add Lighthouse CI as a GitHub status check (optional)

GitHub status checks let you see the status of your Lighthouse CI run in the GitHub UI. If you want to turn the performance and accessibility checks into GitHub status checks, then do the following:

  1. Install the Lighthouse CI GitHub app as the owner of your theme's repo, and then copy the token provided.
  2. In your theme's GitHub repo, create a new environment secret named LHCI_GITHUB_APP_TOKEN. The value should be the token from the previous step.
  3. In the GitHub Action workflow file that you created in Create a new GitHub Action workflow, add a new configuration attribute called lhci_github_app_token. The attribute's value should be a reference to the LHCI_GITHUB_APP_TOKEN secret:

  4. Commit this code and create a pull request. You should see a GitHub Action that runs Lighthouse on your pull request’s code.

Your PRs will now pass or fail depending on whether they pass the Lighthouse CI checks.

Arguments

The Shopify Lighthouse CI GitHub Action accepts the following arguments the the workflow configuration:

Attribute Description Required
app_id Your private app's API key. yes
app_password Your private app's password. yes
store Your store's myshopify.com URL, in the format your-store-name.myshopify.com. yes
password The password for your store. Required for password-protected stores such as development stores. no
product_handle The product handle to run the product page Lighthouse test on. If no handle is specified, then the first product is used. no
collection_handle The collection handle to run the collection page Lighthouse test on. If no handle is specified, then the first product is used. no
lhci_min_score_performance The minimum performance score for a Lighthouse audit to be marked as passed. This value must be a decimal number between 0 and 1. The default value is 0.6. no
lhci_min_score_accessibility The minimum accessibility score for a Lighthouse audit to be marked as passed. This value must be a decimal number between 0 and 1. The default value is 0.9. no

Accepted tokens for GitHub status checks

You need to provide one of the following tokens to log Lighthouse CI runs as GitHub status checks. To understand the difference between the two token types, refer to the Lighthouse CI documentation.

Attribute Description
lhci_github_app_token A token for the Lighthouse GitHub app to access the repo.
lhci_github_token A GitHub personal access token.