- Notifications
You must be signed in to change notification settings - Fork86
Audit URLs using Lighthouse and test performance with Lighthouse CI.
License
treosh/lighthouse-ci-action
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Audit URLs usingLighthouseand test performance withLighthouse CI.
This action integrates Lighthouse CI with Github Actions environment.Making it simple to see failed tests, upload results, run jobs in parallel, store secrets, and interpolate env variables.
It is built in collaboration between Lighthouse Team, Treo (web performance monitoring company), and many excellent contributors.
Features:
- ✅ Audit URLs using Lighthouse v12
- 🎯 Test performance with Lighthouse CI assertions or performance budgets
- 😻 See failed results in the action interface
- 💾 Upload results to a private LHCI server, Temporary Public Storage, or as artifacts
- ⚙️ Full control over Lighthouse CI config
- 🚀 Fast action initialization (less than 1 second)
Run Lighthouse on each push to the repo, test performance budget, save results as action artifacts.
Create.github/workflows/main.yml with the list of URLs to audit using Lighthouse.
name:Lighthouse CIon:pushjobs:lighthouse:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Audit URLs using Lighthouseuses:treosh/lighthouse-ci-action@v12with:urls:| https://example.com/ https://example.com/blogbudgetPath:./budget.json# test performance budgetsuploadArtifacts:true# save results as an action artifactstemporaryPublicStorage:true# upload lighthouse report to the temporary storage
Describe your performance budget using abudget.json.
[ {"path":"/*","resourceSizes": [ {"resourceType":"document","budget":18 }, {"resourceType":"total","budget":200 } ] }]Run Lighthouse and validate against Lighthouse CI assertions.
Create.github/workflows/main.yml with the list of URLs to auditand identify alighthouserc file withconfigPath.
name:Lighthouseon:pushjobs:lighthouse:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Run Lighthouse on urls and validate with lighthousercuses:treosh/lighthouse-ci-action@v12with:urls:'https://exterkamp.codes/'configPath:'./lighthouserc.json'
Make alighthouserc.json file withLHCI assertion syntax.
{"ci": {"assert": {"assertions": {"first-contentful-paint": ["error", {"minScore":0.6 }] } } }}
Upload results to a private LHCI server.
Create.github/workflows/main.yml with the list of URLs to audit using lighthouse,and identify aserverBaseUrl to upload to and antoken to use.
Note: useGitHub secrets to keep your server address hidden!
name:Lighthouseon:pushjobs:lighthouse:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Run Lighthouse on urls and upload data to private lhci serveruses:treosh/lighthouse-ci-action@v12with:urls:'https://example.com/'serverBaseUrl:${{ secrets.LHCI_SERVER_URL }}serverToken:${{ secrets.LHCI_SERVER_TOKEN }}
Audit with custom Chrome options and custom Lighthouse config.
Create.github/workflows/main.yml with the list of URLs to audit andidentify alighthouserc file withconfigPath.
name:Lighthouseon:pushjobs:lighthouse:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Run Lighthouse on urls with lighthousercuses:treosh/lighthouse-ci-action@v12with:urls:'https://example.com/'configPath:'./lighthouserc.json'
Chrome flags can be set directly in thelighthouserc'scollect section.
{"ci": {"collect": {"numberOfRuns":1,"settings": {"chromeFlags":"--disable-gpu --no-sandbox --no-zygote" } } }}Custom Lighthouse config can be defined in a seperate Lighthouse config usingthecustom Lighthouse config syntax.This is then referenced by thelighthouserc file in theconfigPath.
{"ci": {"collect": {"numberOfRuns":1,"settings": {"configPath":"./lighthouse-config.js" } } }}Then put all the custom Lighthouse config in the file referenced in thelighthouserc.
module.exports={extends:'lighthouse:default',settings:{emulatedFormFactor:'desktop',audits:[{path:'metrics/first-contentful-paint',options:{scorePODR:800,scoreMedian:1600}}],},}
Test a static site without having to deploy it.
Create.github/workflows/main.yml and identify alighthouserc file with astaticDistDir config.
name:Lighthouseon:pushjobs:static-dist-dir:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Run Lighthouse against a static dist diruses:treosh/lighthouse-ci-action@v12with:# no urls needed, since it uses local folder to scan .html filesconfigPath:'./lighthouserc.json'
{"ci": {"collect": {"staticDistDir":"./dist" } }}Inside yourstaticDistDir there should be html files that make up your site.LHCI will run a simple static webserver to host the files, then run an auditagainst each of them. More details on this process are in theLighthouse CI docs.
Integrate Lighthouse CI with Netlify
It waits for Netlify to finish building a preview and then uses a built version to check performance.Hence, recipe is a composition of 2 actions:Wait for Netlify Actionand Lighthouse CI Action.
name:Lighthouse CI for Netlify siteson:pull_requestjobs:build:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Wait for the Netlify Previewuses:jakepartusch/wait-for-netlify-action@v1.4id:netlifywith:site_name:'gallant-panini-bc8593' -name:Audit URLs using Lighthouseuses:treosh/lighthouse-ci-action@v12with:urls:| ${{ steps.netlify.outputs.url }} ${{ steps.netlify.outputs.url }}/products/budgetPath:./budget.jsonuploadArtifacts:true
Use URLs interpolation to pass secrets or environment variables
URLs support interpolation of process env variables so that you can write URLs like:
name:Lighthouse CIon:pushjobs:lighthouse:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Run Lighthouse and test budgetsuses:treosh/lighthouse-ci-action@v12with:urls:| https://pr-$PR_NUMBER.staging-example.com/ https://pr-$PR_NUMBER.staging-example.com/blogbudgetPath:./budgets.jsontemporaryPublicStorage:trueenv:PR_NUMBER:${{ github.event.pull_request.number }}
Use with a Lighthouse plugin.
Combine thefield performance plugin with Github Actions.
name:Lighthouse CI with a pluginon:pushjobs:lighthouse:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -run:npm install# install dependencies, that includes Lighthouse plugins -name:Audit URLs with Field Performance Pluginuses:treosh/lighthouse-ci-action@v12with:urls:| https://www.example.com/configPath:'.lighthouserc.json'temporaryPublicStorage:true
{"ci": {"collect": {"settings": {"plugins": ["lighthouse-plugin-field-performance"] } } }}Add a plugin as a dependency, so it's installed locally:
{"devDependencies": {"lighthouse-plugin-field-performance":"^2.0.1" }}Use `output` for a powerful composition with other actions
# Example of output usagename:LHCI-output-webhookon:pushjobs:output-webhook:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Use output for sending data to API.id:LHCIActionuses:./with:urls:| https://treo.sh/ -name:Webhookuses:denar90/webhook-action@0.1.1with:webhookUrl:${{secrets.ACTION_WEBHOOK_URL}}data:'{ "links": ${{steps.LHCIAction.outputs.links}}, "manifest": ${{steps.LHCIAction.outputs.manifest}} }'
GitHub Action workflow on self-hosted GitHub runner (e.g. on-premise)
name:Lighthouse CIon:pushjobs:lighthouse:runs-on:[self-hosted, your-custom-label]steps: -uses:actions/checkout@v4 -name:install Node.js -uses:browser-actions/setup-chrome@latest -run:chrome --versionuses:actions/setup-node@v3with:node-version:${{YOUR_REQUIRED_NODE_JS_VERSION}} -name:Audit URLs using Lighthouseuses:treosh/lighthouse-ci-action@v12with:urls:| https://example.com/ https://example.com/blog[...]
Dynamically generate URLs
Use github-script or any other means to dynamically generate a list of URLs to test
jobs:lighthouse:runs-on:ubuntu-lateststeps: -uses:actions/checkout@v4 -name:Generate URLsid:urlsuses:actions/github-script@v6with:github-token:${{ secrets.GITHUB_TOKEN }}script:| const globber = await glob.create('elements/*/demo/*.html'); const files = await globber.glob(); const urls = files .map(x => x.match(/([\w-]+)/)[1]) .map(x => `${${{ env.DOMAIN }}}/components/${x}/demo/`) .join('\n'); core.setOutput('urls', urls); -name:Lighthouse CI Actionid:lighthouseuses:treosh/lighthouse-ci-action@v8with:urls:| ${{ steps.urls.outputs.urls }}
Explore more workflows inpublic examples.Submit a pull request with a new one if they don't cover your use case.
Provide the list of URLs separated by a new line.Each URL is audited using the latest version of Lighthouse and Chrome preinstalled on the environment.
urls:| https://example.com/ https://example.com/blog https://example.com/pricing
Upload Lighthouse results asaction artifacts to persist results. Equivalent to usingactions/upload-artifact to save the artifacts with additional action steps.
uploadArtifacts:true
Add extra args to theupload command.
uploadExtraArgs:"--extraHeaders.Authorization='Bearer X92sEo3n1J1F0k1E9' --extraHeaders.Foo='Bar'"
Upload reports to thetemporary public storage.
Note: As the name implies, this is temporary and public storage. If you're uncomfortable with the idea of your Lighthouse reports being storedon a public URL on Google Cloud, use a privateLHCI server. Reports are automatically deleted 7 days after upload.
temporaryPublicStorage:true
Use a performance budget to keep your page size in check.Lighthouse CI Action will fail the build if one of the URLs exceeds the budget.
Learn more about thebudget.json spec andpractical use of performance budgets.
budgetPath:./budget.json
Specify the number of runs to do on each URL.
Note: Asserting against a single run can lead to flaky performance assertions.Use
1only to ensure static audits like Lighthouse scores, page size, or performance budgets.
runs:3
Set a path to a customlighthouserc file for full control of the Lighthouse environment and assertions.
Uselighthouserc to configure the collection of data (via Lighthouse config and Chrome Flags), and CI assertions (via LHCI assertions).
configPath:./lighthouserc.json
If some configurations aren't set using action parameters, the settings are fetched from the config file provided here.
Upload Lighthouse results to a privateLHCI server by specifying bothserverBaseUrl andserverToken.This will replace uploading totemporary-public-storage.
serverBaseUrl:${{ secrets.LHCI_SERVER_BASE_URL }}serverToken:${{ secrets.LHCI_SERVER_TOKEN }}
Note: UseGithub secrets to keep your token hidden!
Lighthouse servers can be protected with basic authenticationLHCI server basic authentication by specifying bothbasicAuthUsername andbasicAuthPassword will authenticate the upload.
basicAuthUsername:${{ secrets.LHCI_SERVER_BASIC_AUTH_USERNAME }}basicAuthPassword:${{ secrets.LHCI_SERVER_BASIC_AUTH_PASSWORD }}
Note: UseGithub secrets to keep your username and password hidden!
Use outputs to compose results of the LHCI Action with other Github Actions, like webhooks, notifications, or custom assertions.
A path to.lighthouseci results folder:
/Users/lighthouse-ci-action/.lighthouseciA JSON string with a links to uploaded results:
{'https://treo.sh/':'https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1593981455963-59854.report.html'...}
A JSON string with assertion results:
[{name:'maxNumericValue',expected:61440,actual:508455,values:[508455],operator:'<=',passed:false,auditProperty:'total.size',auditId:'resource-summary',level:'error',url:'https://treo.sh/',auditTitle:'Keep request counts low and transfer sizes small',auditDocumentationLink:'https://developers.google.com/web/tools/lighthouse/audits/budgets',}, ...]
A JSON string with report results (LHCI docs reference):
[ {"url":"https://treo.sh/","isRepresentativeRun":true,"htmlPath":"/Users/lighthouse-ci-action/.lighthouseci/treo_sh-_-2020_07_05_20_37_18.report.html","jsonPath":"/Users/lighthouse-ci-action/.lighthouseci/treo_sh-_-2020_07_05_20_37_18.report.json","summary": {"performance":0.99,"accessibility":0.98,"best-practices":1,"seo":0.96,"pwa":0.71 } }]
About
Audit URLs using Lighthouse and test performance with Lighthouse CI.