Onboarding Guides
Build Tokens and Admin Tokens
LHCI has two built-in authentication mechanisms enabled by default: the build token and the admin token.
The build token allows a user to upload new data to a particular project, but does not allow the destruction or editing of any historical data. If your project is open source and you want to collect Lighthouse data on pull requests from external contributors then you should consider the build token to be public knowledge.
The admin token allows a user to edit or delete data from a particular project. The admin token should only be shared with trusted users and never placed in the CI environment, even in open source projects with external contributors. Anyone with the admin token can delete the entire project's data.
All other actions on the server including listing projects, viewing project and build data, and creating new projects are open to anyone with HTTP access. If you'd like to protect these actions, see the other two authentication mechanisms.
If you forget either of these tokens you will need to connect directly to the storage of the server to reset them using the lhci wizard command.
Registering a property with lighthouse CI
For registering a web property we have to go through the interactive steps with the lhci wizard command.
Eg:
➜ ~ lhci wizard
? Which wizard do you want to run? new-project
? What is the URL of your LHCI server? https://lighthouse.one.redhat.com
? What would you like to name the project? platforms
? Where is the project's code hosted? https://github.com/<org>/<repo>
? What branch is considered the repo's trunk or main branch? master
Created project platforms (cee828ca-2531-4b5e-87d8-cb9ba2ca2d4c)!
Use build token c26c97e3-82fe-4e5f-a49b-004761a7eed4 to add data.
Use admin token 2alsM7lA7cl9WQav0R1tf92yASNVR78CoVdSJMNp to manage data. KEEP THIS SECRET!
➜ ~
After obtaining the build and admin tokens we can upload and manage the lighthouse report in the lighthouse CI server.
Setting up the auditing configuration
Lighthouse CI configuration can be managed through a config file, environment variables, and CLI flag overrides. Lighthouse CI will automatically look for a configuration file in the current working directory in the following priority order:
- .lighthouserc.js
- lighthouserc.js
- .lighthouserc.json
- lighthouserc.json
- .lighthouserc.yml
- lighthouserc.yml
- .lighthouserc.yaml
- lighthouserc.yaml
The structure of the config file is segmented by command. Any options you see for a particular command can be set by the property of the same name in the config file.
Collect
Runs Lighthouse n times and stores the LHRs in a local .lighthouseci/ folder.
| Options | Description |
|---|---|
| method | The method used to run Lighthouse. There are currently two options available, "node" which runs Lighthouse locally via node, and "psi" which runs Lighthouse by making a request to the PageSpeed Insights API. The PageSpeed Insights method has the major limitation that only sites publicly available over the internet can be tested and no other collection options will be respected. |
| headful | Boolean that controls whether Chrome is launched in headless or headful mode. This flag does not apply when using puppeteerScript. |
| additive | Boolean that controls whether the .lighthouseci directory is cleared before starting. By default, this directory is cleared on every invocation of lhci collect to start fresh. |
| url | An array of the URLs that you'd like Lighthouse CI to collect results from. |
| staticDistDir | The path to the directory where the project's productionized static assets are kept. Lighthouse CI uses this to spin up a static server on your behalf that will be used to load your site. |
| isSinglePageApplication | Boolean that controls whether the static server started in staticDistDir should act like a single-page application that serves index.html instead of a 404 for unrecognized paths. This flag has no function when staticDistDir is not set. |
| chromePath | The path of the Chrome executable to use for puppeteerScript and running Lighthouse |
| puppeteerScript | An optional path to a JavaScript file that exports a function that uses puppeteer to login to your page, setup cache data, or otherwise manipulate the browser before Lighthouse is run. |
| puppeteerLaunchOptions | An object of options to pass to puppeteer's launch method. Only used when puppeterScript is set. |
| psiApiKey | The API key to use for making PageSpeed Insights requests. Required if using method=psi. You can obtain a PSI API key from Google APIs. |
| psiApiEndpoint | The API endpoint to hit for making a PageSpeed Insights request. It is very unlikely you should need to use this option. Only use this if you have self-hosted a custom version of the PSI API. |
| psiStrategy | Use this option to change the strategy to use for PageSpeed Insights runner method. Use mobile or desktop. The default value is mobile. |
| startServerCommand | The shell command to use to start the project's webserver. LHCI will use this command to start the server before loading the urls and automatically shut it down once collection is complete. |
| startServerReadyPattern | The regex pattern to look for in the server command's output before considering the server ready for requests. Only used when startServerCommand is set. |
| startServerReadyTimeout | The maximum amount of time in milliseconds to wait for startServerCommand to print the startServerReadyPattern before continuing anyway. Only used when startServerCommand is set. |
| settings | The Lighthouse CLI flags to pass along to Lighthouse. This can be used to change configuration of Lighthouse itself. Eg: Port, auditMode, gatherMode, output, outputPath ,channel, cli-flags-path |
| numberOfRuns | The number of times to collect Lighthouse results on each url. This option helps mitigate fluctations due to natural page variability. |
Assert
Asserts the conditions in the Lighthouse CI config and exits with the appropriate status code if there were any failures.
| Options | Description |
|---|---|
| preset | The assertions preset to extend [choices: "lighthouse:all", "lighthouse:recommended", "lighthouse:no-pwa"] lighthouse:all - Asserts that every audit received a perfect score. This is extremely difficult to do. Only use as a base on very high quality, greenfield projects and lower the tresholds as needed. lighthouse:recommended - Asserts that every audit outside performance received a perfect score, that no resources were flagged for performance opportunities, and warns when metric values drop below a score of 90. This is a more realistic base that disables hard failures for flaky audits. lighthouse:no-pwa - lighthouse:recommended but without any of the PWA audits enabled. |
| assertions | The assertions to use Categories - The score of any category in Lighthouse can also be asserted. Assertions are keyed by categories: categoryId and follow the same eslint-style format as audit assertions. Note that this just affects the category score and will not affect any assertions on individual audits within the category. Levels - There are three Lighthouse CI assertion levels [choices: "off", "warn", "error"]. Properties - The score, details.items.length, and numericValue properties of audit results can all be checked against configurable thresholds. Use minScore, maxLength, and maxNumericValue properties, respectively, in the options object to control the assertion. Aggregation Methods - There are multiple strategies for aggregating the results before asserting the threshold. Median - Use the median value from all runs. Optimistic - Use the value that is most likely to pass from all runs. Pessimistic - Use the value that is least likely to pass from all runs. Median-Run - Use the value of the run that was determined to be "most representative" of all runs based on key performance metrics. Note that this differs from median because the audit you're asserting might not be the performance metric that was used to select the median-run. User Timings - Your custom user timings using performance.mark and performance.measure can be asserted against as well. |
| assertMatrix | can be used to assert against multiple URLs at the same time. When checking the results of runs against multiple URLs, different assertions can be made for different URL patterns. |
| budgetsFile | Instead of configuring using Lighthouse CI assertions against Lighthouse audits, a budget.json file can be used instead. |
| includePassedAssertions | Boolean that controls whether passed assertions should be included in the output. |
Upload
Saves the runs in the .lighthouseci/ folder to desired target and sets a GitHub status check when the GitHub token is available.
| Options | Description |
|---|---|
| target | The type of target to upload the data to. If set to anything other than "lhci", some of the options will not apply. When to use target=temporary-public-storage: - You want to setup Lighthouse CI as quickly as possible without any costs. - You're OK with your reports being available to anyone on the internet with the link. - You're OK with your reports being automatically deleted after a few days. - You're OK with your reports being stored on GCP Cloud Storage. When to use target=lhci: - You want to store Lighthouse reports for longer than a few days. - You want to control access to your Lighthouse reports. - You've setup a Lighthouse CI server. When to use target=filesystem: You want to process the raw Lighthouse results yourself locally. You want access to the report files on the local filesystem. You don't want to upload the results to a custom location that isn't supported by Lighthouse CI. |
| token | The build token for your Lighthouse CI project. Required when using target=lhci. This token should be given to you by lhci wizard --wizard=new-project. If you've forgotten your token, connect directly to your server and run lhci wizard --wizard=reset-build-token. |
| ignoreDuplicateBuildFailure | Boolean flag that controls whether upload failures due to duplicate build hashes should be ignored. |
| githubToken | The GitHub token to use when setting a status check on a GitHub PR. Use this when the project is hosted on GitHub and not using the official GitHub App. |
| githubApiHost | The GitHub API host to use when attempting to set a status check. Use this when the project is hosted on a private GitHub enterprise server and not using the public GitHub API. |
| githubAppToken | The GitHub App token returned when installing the GitHub App. Use this to set status checks on GitHub PRs when using the official GitHub App. |
| githubStatusContextSuffix | The suffix to use when setting the status check on a GitHub PR. |
| extraHeaders | A map of additional headers to add the requests made to the LHCI server. Useful for adding bespoke auth tokens. |
| basicAuth | An object containing a username and password pair for authenticating with a Basic auth protected LHCI server. Use this setting when you've protected your LHCI server with Basic auth. |
| serverBaseUrl | The base URL of the LHCI server to upload to. Required when using target=lhci. |
| uploadUrlMap | Boolean that controls whether to update the latest build in temporary public storage associated with this repo. If you use master as your default branch, DO NOT use this option. If you don't use master as your default branch, set this option when you upload results from your actual default branch. |
| urlReplacementPatterns | A list of replacement patterns that will mask differences in tested URLs that you wish to hide for display or treat as the same. The urlReplacementPatterns are used to identify the same URLs for diff comparisons and as preprocessing for GitHub status check labels. |
| outputDir | The directory relative to the current working directory in which to output a manifest.json along with the Lighthouse reports collected. |
| reportFilenamePattern | The pattern to use for report filenames when writing the reports to the filesystem. |