{"id":15018143,"url":"https://github.com/lfre/lightkeeper","last_synced_at":"2025-08-23T17:40:10.399Z","repository":{"id":35004449,"uuid":"187402368","full_name":"lfre/lightkeeper","owner":"lfre","description":"Run Lighthouse tests in Pull Requests for multiple URLs with custom budgets","archived":false,"fork":false,"pushed_at":"2023-01-09T17:50:17.000Z","size":1897,"stargazers_count":86,"open_issues_count":28,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-29T21:10:40.107Z","etag":null,"topics":["app","ci","github","lighthouse","performance","performance-budget","probot"],"latest_commit_sha":null,"homepage":"https://lightkeeper.dev","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lfre.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}},"created_at":"2019-05-18T20:28:57.000Z","updated_at":"2023-01-23T02:17:12.000Z","dependencies_parsed_at":"2023-01-15T11:51:07.964Z","dependency_job_id":null,"html_url":"https://github.com/lfre/lightkeeper","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/lfre%2Flightkeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lfre%2Flightkeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lfre%2Flightkeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lfre%2Flightkeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lfre","download_url":"https://codeload.github.com/lfre/lightkeeper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237852545,"owners_count":19376706,"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":["app","ci","github","lighthouse","performance","performance-budget","probot"],"created_at":"2024-09-24T19:51:30.815Z","updated_at":"2025-02-08T18:31:36.268Z","avatar_url":"https://github.com/lfre.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n\n![](https://raw.githubusercontent.com/wiki/lfre/lightkeeper/images/lightkeeper-header-250.png)\n\n# ⚓ _Lightkeeper_ (alpha)\n\n![](https://badgen.net/github/status/lfre/lightkeeper/master)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://raw.githubusercontent.com/lfre/lightkeeper/master/LICENSE)\n[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/alfredolo/5)\n\nRun [Lighthouse](https://developers.google.com/web/tools/lighthouse/) tests in Pull Request URLs with multiple routes. Prevent regressions through custom budgets in a flexible and extensible configuration.\n\n[![](https://img.shields.io/static/v1.svg?label=INSTALL\u0026message=GITHUB\u0026color=brightgreen\u0026link=https://github.com/apps/lightkeeper-ci\u0026style=for-the-badge)](https://github.com/apps/lightkeeper-ci)\n\n![](https://raw.githubusercontent.com/wiki/lfre/lightkeeper/images/lightkeeper-status.gif)\n![](https://raw.githubusercontent.com/wiki/lfre/lightkeeper/images/warnings.png) ![](https://raw.githubusercontent.com/wiki/lfre/lightkeeper/images/failures.png)\n---\n## It works with:\n\n_Any Github Check Run, Deployment or Status, including:_\n\n![](https://raw.githubusercontent.com/wiki/lfre/lightkeeper/images/logos/supported-ci.jpg)\n\n\u003c/div\u003e\n\n## The Problem\n\nThere is a disconnect between the state of performance tooling, and the desire teams have to move faster but safer.\n\nOn one side, there are several tools to monitor production/staging environments, but on the other side, teams are looking to have full CI/CD integrated where Pull Requests go live upon merge.\n\nThis requires that all testing must happen at the Pull Request level on a unique URL per branch and/or commit, and while there are tools that support these types of Performance tests, they all suffer from common problems:\n\n* **Single URL.**\n    * A site is not a single URL. For several sites the most important page is a dynamic route **not** the homepage.\n  \n* **Run and block the CI build process.**\n    * When all tests run on every Pull Request, their intention is to block merging if any issues are found, but during the different stages of development, the single most important task is to get an URL preview. Failing a build on another stage might require a dive into the build dashboard or logs to distinguish errors. Sending a notification, or posting a comment at the end of a specific task can help with this, but it requires additional effort.\n  \n* **If used for multiple URLs manually, there is no consolidated report.**\n    * Pull Request pages can be overwhelming at times. From Peer Reviews to comments added by other tools, posting a comment per URL is too noisy.\n\n## This Solution \n\nLightkeeper attempts to solve each one of these issues: 🤞\n\n* **Multiple URL support.**\n    * Configure 1 to many URL routes, from separate domains or extending a base URL.\n  \n* **Decoupled from the CI build process.**\n    * It runs when the CI build finishes and is successful. For complex build set ups, the [Lightkeeper Bot](#lightkeeper-bot) is available to trigger an event. This allows the build to continue without stalling waiting for a response.\n  \n* **Consolidated reports, and expandable comments.**\n    * It posts a consolidated report of all tests, and includes only relevant information in the comment.\n    ![](https://raw.githubusercontent.com/wiki/lfre/lightkeeper/images/comment.gif)\n\nMost importantly, Lightkeeper provides granular control of settings per route, from budgets to the Lighthouse endpoint and its options, including chrome flags in the puppeteer configuration. \n\nSee [Motivation](https://github.com/lfre/lightkeeper/wiki/Motivation).\n\n## Getting Started\n\nAdd a `lightkeeper.json` file in a `.github` folder. Start from the [default configuration](/configuration/lightkeeper.json).\n\n \u003e This is the only file Lightkeeper has access in your code.\n\nThere are 3 required fields: `baseUrl`, `ci`, and `type`. Lightkeeper is a budgeting tool, so at least a single type of budget is needed to run sucessfully.\n\n- Replace the `baseUrl` with a valid URL. Since Pull Request URLs are dynamic, macros are available:\n  \n  | Macro | Details |\n  | ----  | ------  |\n  | `{pr_number}` | The Pull Request Number. |\n  | `{repo}` | A _slugified_ repo name. |\n  | `{branch}` | A _slugified_ branch name. |\n  | `{commit_hash}` | The full commit SHA. |\n  | `{commit_hash:n}` | A trimmed SHA, where `n` is a digit. |\n  | *`{target_url}` | The target url from the Github Response. |\n  | **`{environment_url}` | The url from the Deployment status. |\n\n  \\* Available for statuses and deployments.\n\n  \\** Available for deployments only.\n\n- Replace `ci` and `type` for your CI tool. Examples:\n\n  \u003cdetails\u003e\n    \u003csummary\u003eCircle CI\u003c/summary\u003e\n\n    ```json\n    {\n      \"ci\": \"circleci\",\n      \"type\": \"check\"\n    }\n    ```\n    \u003e CircleCI uses statuses by default, but also provide a [Github Checks integration](https://github.com/apps/circleci-checks).\n\n    If multiple checks are running (e.g: Integration Tests, Mobile Tests, etc)\n\n    Use the full name of the specific workflow as it appears in Github, instead of `circleci`.\n  \u003c/details\u003e\n  \u003cdetails\u003e\n    \u003csummary\u003eNetlify\u003c/summary\u003e\n\n    ```json\n    {\n      \"baseUrl\": \"{target_url}\",\n      \"ci\": \"netlify\",\n      \"type\": \"status\"\n    }\n    ```\n  \u003c/details\u003e\n  \u003cdetails\u003e\n    \u003csummary\u003eTravis CI\u003c/summary\u003e\n\n    ```json\n    {\n      \"ci\": \"travis-ci\",\n      \"type\": \"check\"\n    }\n    ```\n  \u003c/details\u003e\n  \u003cdetails\u003e\n    \u003csummary\u003eZeit Now\u003c/summary\u003e\n\n    ```json\n    {\n      \"baseUrl\": \"{environment_url}\",\n      \"ci\": \"now\",\n      \"type\": \"deployment\"\n    }\n    ```\n  \u003c/details\u003e\n\n\u003e If you're unsure about the name of your CI tool, it's the name displayed under `Developer` in the application page:\n\u003e https://github.com/apps/[app-name]\n\n**NOTE:** These providers and their settings can change. If the provided `ci` name above does not work, use the full visible name:\n\n![](https://raw.githubusercontent.com/wiki/lfre/lightkeeper/images/full-ci-name.png)\n\n## Configuration\n\nVisit the [wiki](https://github.com/lfre/lightkeeper/wiki/Configuration-Options) for a full list of configuration options.\n\nAdditionally, there is a [custom configuration](/configuration/lightkeeper(custom).json) example.\n\n## Lightkeeper Bot 🤖\n\nDo you have a complex build pipeline that performs several tasks internally?\nUsing the [Lightkeeper Bot](https://www.npmjs.com/package/lightkeeperbot) with the app installed, you can start the process manually without stalling the build:\n\n- Install:\n  \n  `npm i --save-dev lightkeeperbot`\n\n- In your CI tool, run:\n  \n  `npx lightkeeperbot \u003cbaseUrl\u003e [--options]`\n  \u003e Lightkeeper Bot defaults to Travis CI environment variables.\n\nSee the [full docs](https://www.npmjs.com/package/lightkeeperbot).\n\n---\n\n## Tools\n\n- [probot](https://probot.github.io/)\n- [lighthouse](https://github.com/GoogleChrome/lighthouse)\n- [chrome-aws-lambda](https://github.com/alixaxel/chrome-aws-lambda)\n- [puppeteer](https://github.com/GoogleChrome/puppeteer)\n\n## Inspiration\n\n- [Lighthouse Bot](https://github.com/GoogleChromeLabs/lighthousebot)\n- [Lighthouse GH Reporter](https://github.com/carlesnunez/lighthouse-gh-reporter)\n\n## FAQ\n\n- **Why isn't this part of the Lighthouse Bot?**\n  - That was my original intention after reading their [FAQ](https://github.com/GoogleChromeLabs/lighthousebot#why-not-a-github-webhook), but after I realized the best format is a Github App along with other features, it was clear the changes would be too drastic. However, `Lightkeeper` is compatible with their Ligthouse server located at https://builder-dot-lighthouse-ci.appspot.com/ci, if you choose to continue using it.\n\n- **Why isn't this a Github Action?**\n  - I wanted it to be and still do. However, besides the fact that Github Actions are (at the time of writing) Private Beta; it can lead to visual noise when skipping a check. \u003cbr\u003e![](https://pbs.twimg.com/media/D-9aZn2WwAUv6Em?format=jpg\u0026name=small)\u003cbr\u003e\n  If in the future, Github could allow a subset level of notifications per event (e.g: check run starts vs check run complete), and possibly a filter on `status` (only run action when a check run completes and is succesful); I'd be more than happy to switch since it removes the need for a server, and allows for securely sharing secrets.\n  \n- **I'm getting a Lighthouse error in my reports.**\n  - If your page fails in [Page Speed Insights](https://developers.google.com/speed/pagespeed/insights/), it will most likely fail in Lightkeeper too. Consider changing the Lighthouse `throttling` options, or device emulation.\n\n## Related Projects\n\n- [Performance Budgets (Docker)](https://github.com/boyney123/performance-budgets)\n- [Zeit Integrations Platform](https://zeit.co/blog/zeit-now-integrations-platform)\n\n## Contributing\n\nPlease open an issue if you have any questions, feature requests or problems, an example configuration for reproduction is deeply appreciatted. 👍\n\n## Donating\n\nIf you find this tool useful, and want me to spend more time on it. Consider **[Donating](https://www.paypal.me/alfredolo/5)**.\n\n---\n\nAGPL, Copyright (c) 2019 Alfredo Lopez\n\n\n","funding_links":["https://www.paypal.me/alfredolo/5","https://www.paypal.me/alfredolo/5)*"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flfre%2Flightkeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flfre%2Flightkeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flfre%2Flightkeeper/lists"}