{"id":15131502,"url":"https://github.com/googlechromelabs/lighthousebot","last_synced_at":"2025-09-28T23:30:52.381Z","repository":{"id":66027587,"uuid":"85022121","full_name":"GoogleChromeLabs/lighthousebot","owner":"GoogleChromeLabs","description":"Run Lighthouse in CI, as a web service, using Docker. Pass/Fail GH pull requests.","archived":true,"fork":false,"pushed_at":"2020-07-07T09:41:34.000Z","size":319,"stargazers_count":2238,"open_issues_count":45,"forks_count":127,"subscribers_count":34,"default_branch":"master","last_synced_at":"2024-04-18T12:29:48.730Z","etag":null,"topics":["ci","docker","headless-chrome","lighthouse","pwa","testing","travis"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleChromeLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-03-15T02:56:43.000Z","updated_at":"2024-04-15T20:55:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"9a7336f5-6eb9-448b-bed8-990023236a52","html_url":"https://github.com/GoogleChromeLabs/lighthousebot","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleChromeLabs%2Flighthousebot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleChromeLabs%2Flighthousebot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleChromeLabs%2Flighthousebot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleChromeLabs%2Flighthousebot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleChromeLabs","download_url":"https://codeload.github.com/GoogleChromeLabs/lighthousebot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234569824,"owners_count":18854133,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","docker","headless-chrome","lighthouse","pwa","testing","travis"],"created_at":"2024-09-26T03:42:31.972Z","updated_at":"2025-09-28T23:30:51.936Z","avatar_url":"https://github.com/GoogleChromeLabs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lighthouse Bot (deprecated)\n\n**Update:** LighthouseBot has been deprecated and we now recommend using the official [Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci) project to automate running Lighthouse for every commit, view the changes, and prevent regressions\n\n## Historical README below\n\nThis repo contained the frontend and backend for running Lighthouse in CI and integration with Github Pull Requests. An example web service is hosted for demo purposes.\n\n## Auditing GitHub Pull Requests\n\n\u003e Please note: This drop in service is considered **Beta**. There are no SLAs or uptime guarantees. If you're interested in running your own CI server in a Docker container, check out [Running your own CI server](#running-your-own-ci-server).\n\nLighthouse can be setup as part of your CI on **Travis only**. As new pull requests come in, the **Lighthouse Bot tests the changes and reports back the new score**.\n\n\u003cimg width=\"700\" alt=\"Run Lighthouse on Github PRs\" src=\"https://user-images.githubusercontent.com/238208/27059055-70ba6e86-4f89-11e7-8ead-932aab0f2634.png\"\u003e\n\nTo audit pull requests, do the following:\n\n### 1. Initial setup\n\n#### Add the lighthousebot to your repo\n\nFirst, add [lighthousebot](https://github.com/lighthousebot) as a collaborator on your repo. Lighthouse CI uses an OAuth token scoped to the `repo` permission in order to update the status of your PRs and post comments on the issue as the little Lighthouse icon.\n\n_* Until Lighthousebot accepts your invitation to collaborate, which is currently a lengthy manual process, it does not have permission to update the status of your PRs. However, it will post a comment on your PR._\n\n#### Get an API Key\n\n[Request an API Key](https://goo.gl/forms/9BzzhHd1sKzsvyC52). API keys will eventually be\nenforced and are necessary so we can contact you when there are changes to the CI system.\n\nOnce you have a key, update Travis settings by adding an `LIGHTHOUSE_API_KEY` environment variables with your key:\n\n\u003cimg width=\"875\" alt=\"Travis LIGHTHOUSE_API_KEY env variable \" src=\"https://user-images.githubusercontent.com/2837064/32105842-2635de42-bb2a-11e7-983a-921a802d38b3.jpg\"\u003e\n\nThe `lighthousebot` script will include your key in requests made to the CI server.\n\n### 2. Deploy the PR\n\nWe recommend deploying your PR to a real staging server instead of running a local server on Travis.\nA staging environment will produce realistic performance numbers that are\nmore representative of your production setup. The Lighthouse report will be more accurate.\n\nIn `.travis.yml`, add an  `after_success` that **deploys the PR's changes to a staging server**.\n\n```bash\nafter_success:\n  - ./deploy.sh # TODO(you): deploy the PR changes to your staging server.\n```\n\n Since every hosting environment has different deployment setups, the implementation of `deploy.sh` is left to the reader.\n\n\u003e **Tip:** Using Google App Engine? Check out [`deploy_pr_gae.sh`](https://github.com/GoogleChrome/chromium-dashboard/blob/master/travis/deploy_pr_gae.sh) which shows how to install the GAE SDK and deploy PR changes programmatically.\n\n### 3. Call lighthousebot\n\nInstall the script:\n\n    npm i --save-dev https://github.com/GoogleChromeLabs/lighthousebot\n\nAdd an NPM script to your `package.json`:\n\n```js\n\"scripts\": {\n  \"lh\": \"lighthousebot\"\n}\n```\n\nNext, in `.travis.yml` call [`npm run lh`][runlighthouse-link] as the last step in `after_success`:\n\n```yml\ninstall:\n  - npm install # make sure to install the deps when Travis runs.\nafter_success:\n  - ./deploy.sh # TODO(you): deploy the PR changes to your staging server.\n  - npm run lh -- https://staging.example.com\n```\n\nWhen Lighthouse is done auditing the URL, the bot will post a comment to the pull\nrequest containing the updated scores:\n\n\u003cimg width=\"779\" alt=\"Lighthouse Github comment\" src=\"https://user-images.githubusercontent.com/238208/46586553-dfffe600-ca34-11e8-9eea-3846b41a4360.png\"\u003e\n\nYou can also opt-out of the comment by using the `--no-comment` flag.\n\n#### Failing a PR when it drops your Lighthouse score\n\nLighthouse CI can prevent PRs from being merged when one of the scores falls\nbelow a specified value. Just include one or more of `--pwa`, `--perf`, `--seo`,\n`--a11y`, or `--bp`:\n\n```yml\nafter_success:\n  - ./deploy.sh # TODO(you): deploy the PR changes to your staging server.\n  - npm run lh -- --perf=96 --pwa=100 https://staging.example.com\n```\n\n\u003cimg width=\"779\" src=\"https://user-images.githubusercontent.com/238208/46586467-e93c8300-ca33-11e8-83ac-401b23227eb0.png\"\u003e\n\n#### Options\n\n```bash\n$ lighthouse-ci -h\n\nUsage:\nrunlighthouse.js [--perf,pwa,seo,a11y,bp=\u003cscore\u003e] [--no-comment] [--runner=chrome,wpt] \u003curl\u003e\n\nOptions:\n  Minimum score values can be passed per category as a way to fail the PR if\n  the thresholds are not met. If you don't provide thresholds, the PR will\n  be mergeable no matter what the scores.\n\n  --pwa        Minimum PWA score for the PR to be considered \"passing\". [Number]\n  --perf       Minimum performance score for the PR to be considered \"passing\". [Number]\n  --seo        Minimum seo score for the PR to be considered \"passing\". [Number]\n  --a11y       Minimum accessibility score for the PR to be considered \"passing\". [Number]\n  --bp         Minimum best practices score for the PR to be considered \"passing\". [Number]\n\n  --no-comment Doesn't post a comment to the PR issue summarizing the Lighthouse results. [Boolean]\n\n  --runner     Selects Lighthouse running on Chrome or WebPageTest. [--runner=chrome,wpt]\n\n  --help       Prints help.\n\nExamples:\n\n  Runs Lighthouse and posts a summary of the results.\n    runlighthouse.js https://example.com\n\n  Fails the PR if the performance score drops below 93. Posts the summary comment.\n    runlighthouse.js --perf=93 https://example.com\n\n  Fails the PR if perf score drops below 93 or the PWA score drops below 100. Posts the summary comment.\n    runlighthouse.js --perf=93 --pwa=100 https://example.com\n\n  Runs Lighthouse on WebPageTest. Fails the PR if the perf score drops below 93.\n    runlighthouse.js --perf=93 --runner=wpt --no-comment https://example.com\n```\n\n## Running on WebPageTest instead of Chrome\n\nBy default, `lighthousebot` runs your PRs through Lighthouse hosted in the cloud. As an alternative, you can test on real devices using the WebPageTest integration:\n\n```bash\nlighthousebot --perf=96 --runner=wpt https://staging.example.com\n```\n\nAt the end of testing, your PR will be updated with a link to the WebPageTest results containing the Lighthouse report!\n\n## Running your own CI server\n\nWant to setup your own Lighthouse instance in a Docker container?\n\nThe good news is Docker does most of the work for us! The bulk of getting started is in [Development](#development). That will take you through initial setup and show how to run the CI frontend.\n\nFor the backend, see [builder/README.md](https://github.com/GoogleChromeLabs/lighthousebot/blob/master/builder/README.md) for building and running the Docker container.\n\nOther changes, to the \"Development\" section:\n\n- Create a personal OAuth token in https://github.com/settings/tokens. Drop it in `frontend/.oauth_token`.\n- Add a `LIGHTHOUSE_CI_HOST` env variable to Travis settings that points to your own URL. The one where you deploy the Docker container.\n\n## Development\n\nInitial setup:\n\n1. Ask an existing dev for the oauth2 token. If you need to regenerate one, see below.\n- Create `frontend/.oauth_token` and copy in the token value.\n\nRun the dev server:\n\n    cd frontend\n    npm run start\n\nThis will start a web server and use the token in `.oauth_token`. The token is used to update PR status in Github.\n\nIn your test repo:\n\n- Run `npm i --save-dev https://github.com/GoogleChromeLabs/lighthousebot`\n- Follow the steps in [Auditing Github Pull Requests](#auditing-github-pull-requests) for setting up\nyour repo.\n\nNotes:\n\n- If you want to make changes to the builder, you'll need [Docker](https://www.docker.com/) and the [GAE Node SDK](https://cloud.google.com/appengine/docs/flexible/nodejs/download).\n- To make changes to the CI server, you'll probably want to run [ngrok](https://ngrok.com/) so you can test against a local server instead of deploying for each change. In Travis settings,\nadd a `LIGHTHOUSE_CI_HOST` env variable that points to your ngrok instance.\n\n##### Generating a new OAuth2 token\n\nIf you need to generate a new OAuth token:\n\n1. Sign in to the [lighthousebot](https://github.com/lighthousebot) Github account. (Admins: the credentials are in the usual password tool).\n2. Visit personal access tokens: https://github.com/settings/tokens.\n3. Regenerate the token. **Important**: this invalidates the existing token so other developers will need to be informed.\n4. Update token in `frontend/.oauth_token`.\n\n#### Deploy\n\nBy default, these scripts deploy to [Google App Engine Flexible containers](https://cloud.google.com/appengine/docs/flexible/nodejs/) (Node). If you're running your own CI server, use your own setup :)\n\nDeploy the frontend:\n\n    npm run deploy YYYY-MM-DD frontend\n\nDeploy the CI builder backend:\n\n    npm run deploy YYYY-MM-DD builder\n\n## Source \u0026 Components\n\nThis repo contains several different pieces for the Lighthouse Bot: a backend, frontend, and frontend UI.\n\n### UI Frontend\n\u003e Quick way to try Lighthouse: https://lighthouse-ci.appspot.com/try\n\nRelevant source:\n\n- `frontend/public/` - UI for https://lighthouse-ci.appspot.com/try.\n\n### Bot CI server (frontend)\n\u003e Server that responds to requests from Travis.\n\nREST endpoints:\n- `https://lighthouse-ci.appspot.com/run_on_chrome`\n- `https://lighthouse-ci.appspot.com/run_on_wpt`\n\n#### Example\n\n**Note:** `lighthousebot` does this for you.\n\n```\nPOST https://lighthouse-ci.appspot.com/run_on_chrome\nContent-Type: application/json\nX-API-KEY: \u003cYOUR_LIGHTHOUSE_API_KEY\u003e\n\n{\n  testUrl: \"https://staging.example.com\",\n  thresholds: {\n    pwa: 100,\n    perf: 96,\n  },\n  addComment: true,\n  repo: {\n    owner: \"\u003cREPO_OWNER\u003e\",\n    name: \"\u003cREPO_NAME\u003e\"\n  },\n  pr: {\n    number: \u003cPR_NUMBER\u003e,\n    sha: \"\u003cPR_SHA\u003e\"\n  }\n}\n```\n\nRelevant source:\n\n- [`frontend/server.js`](https://github.com/GoogleChromeLabs/lighthousebot/blob/master/frontend/server.js) - server which accepts Github pull requests and updates the status of your PR.\n\n### CI backend (builder)\n\u003e Server that runs Lighthouse against a URL, using Chrome.\n\nREST endpoints:\n- `https://lighthouse-ci.appspot.com/ci`\n\n#### Example\n\n**Note:** `lighthousebot` does this for you.\n\n```bash\ncurl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-KEY: \u003cYOUR_LIGHTHOUSE_API_KEY\u003e\" \\\n  --data '{\"output\": \"json\", \"url\": \"https://staging.example.com\"}' \\\n  https://builder-dot-lighthouse-ci.appspot.com/ci\n```\n\n## FAQ\n\n##### Why not deployment events?\n\nGithub's [Deployment API](https://developer.github.com/v3/repos/deployments/) would\nbe ideal, but it has some downsides:\n\n- Github Deployments happen __after__ a pull is merged. We want to support blocking PR\nmerges based on a LH score.\n- We want to be able to audit changes as they're add to the PR. `pull_request`/`push` events are more appropriate for that.\n\n##### Why not a Github Webhook?\n\nThe main downside of a Github webhook is that there's no way to include custom\ndata in the payload Github sends to the webhook handler. For example, how would\nLighthouse know what url to test? With a webhook, the user also has to setup it\nup and configure it properly.\n\nFuture work: Lighthouse Bot could define a file that developer includes in their\nrepo. The bot's endpoint could pull a `.lighthouse_ci` file that includes meta\ndata `{minLighthouseScore: 96, testUrl: 'https://staging.example.com'}`. However,\nthis requires work from the developer.\n\n[runlighthouse-link]: https://github.com/GoogleChromeLabs/lighthousebot/blob/master/runlighthouse.js\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglechromelabs%2Flighthousebot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglechromelabs%2Flighthousebot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglechromelabs%2Flighthousebot/lists"}