{"id":18459040,"url":"https://github.com/liatrio/backstage-dora-plugin","last_synced_at":"2026-03-12T12:39:04.511Z","repository":{"id":255114441,"uuid":"848354691","full_name":"liatrio/backstage-dora-plugin","owner":"liatrio","description":"Backstage plugin to surface an organizations DORA metrics","archived":false,"fork":false,"pushed_at":"2024-11-04T16:26:25.000Z","size":4576,"stargazers_count":34,"open_issues_count":10,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-23T12:05:35.039Z","etag":null,"topics":["backstage","backstage-plugin","dora","dora-devops","dora-metrics"],"latest_commit_sha":null,"homepage":"https://openo11y.dev/human-systems/delivery-metrics/lagging-delivery-indicators/","language":"TypeScript","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/liatrio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-27T15:57:11.000Z","updated_at":"2024-11-12T10:27:12.000Z","dependencies_parsed_at":"2024-08-28T04:24:16.207Z","dependency_job_id":"a724341f-24a2-4335-a9f7-dd1fd2c0bc2e","html_url":"https://github.com/liatrio/backstage-dora-plugin","commit_stats":null,"previous_names":["liatrio/backstage-dora-plugin"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Fbackstage-dora-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Fbackstage-dora-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Fbackstage-dora-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Fbackstage-dora-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liatrio","download_url":"https://codeload.github.com/liatrio/backstage-dora-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230333845,"owners_count":18210133,"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":["backstage","backstage-plugin","dora","dora-devops","dora-metrics"],"created_at":"2024-11-06T08:21:30.146Z","updated_at":"2026-03-12T12:39:04.453Z","avatar_url":"https://github.com/liatrio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Backstage DORA Plugin\n\n[![CodeQL](https://github.com/liatrio/backstage-liatrio-dora-plugin/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/liatrio/backstage-liatrio-dora-plugin/actions/workflows/codeql.yml) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Release](https://github.com/liatrio/backstage-dora-plugin/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/liatrio/backstage-dora-plugin/actions/workflows/release.yml) ![GitHub top language](https://img.shields.io/github/languages/top/liatrio/backstage-dora-plugin)\n\nThis is a plugin for the [Backstage](https://backstage.io/) Project that provides a seamless way to display [DORA Metrics](https://dora.dev/guides/dora-metrics-four-keys/) in your developer portals.\n\nOur goal is to provide an Open Source plugin that works with the Open Telemetry backend collecting your DORA metrics in a non-opinionated manner.\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable-next-line MD036 --\u003e\n**This plugin is currently loosely tied to GitHub and Loki DB, we plan to expand to GitLab and other platforms in the future**\n\u003c!-- prettier-ignore-end --\u003e\n\n## Plugin Architecture\n\n![Dora Backstage Plugin Architecture](./screenshots/dora-backstage-plugin-architecture.drawio.png)\n\n### Links to Modules\n\n- [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector)\n- [liatrio-dora-api](https://github.com/liatrio/liatrio-dora-api)\n- [backstage-dora-plugin](https://github.com/liatrio/backstage-dora-plugin)\n- [react-dora-charts](https://github.com/liatrio/react-dora-charts)\n\n## Components\n\n### `At A Glance`\n\nThis offers you a quick view of the state of a component or service.\n\nDepending on how you have set up your configuration for this plugin, it will show:\n\n- The individual DORA Metrics for the last 30 days\n  - `Deployment Frequency`- The average how often you are deploying, failed or successful\n    - Weekends, unless included, and holidays, if set, are subtracted from timespans that go over them\n  - `Change Lead Time` - The average of time merged to `main` to deployment success\n    - Weekends, unless included, and holidays, if set, are subtracted from timespans that go over them\n  - `Change Failure Rate` - The average number of changes that result in a failed deployment\n  - `Recovery Time` - The average of a failed deployment to the next successful deployment\n    - Regardless of configuration, includes weekends and does not subtract the holidays if set.\n- The DORA Metrics overall trend over the last 30 days\n  - The Trend is calculated on a per-week basis\n  - If a component has gone stale or is too new, you will see a note about there not being enough data to render a trend.\n  - There is an option to also show each DORA Metric as a line on the graph, a legend will appear in this case\n\nHere are some examples:\n\n| Metric View with Details Always Showing                                                                                     | Metric View with Details on Hover                                                                                                          |\n| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| ![Metrics](https://raw.githubusercontent.com/liatrio/backstage-dora-plugin/main/screenshots/ranked/atAGlance.png 'Metrics') | ![Metrics](https://raw.githubusercontent.com/liatrio/backstage-dora-plugin/main/screenshots/ranked/atAGlance_hover.png?raw=true 'Metrics') |\n\n| Overall Trend View                                                                                                              | Overall Trend View with Individual Metric Trends                                                                                          |\n| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| ![Trend](https://raw.githubusercontent.com/liatrio/backstage-dora-plugin/main/screenshots/trend/atAGlance.png?raw=true 'Trend') | ![Trend](https://raw.githubusercontent.com/liatrio/backstage-dora-plugin/main/screenshots/trend/atAGlanceIndividual.png?raw=true 'Trend') |\n\n### `Charts`\n\nThis is a set of charts that for the DORA metrics.\n\nIt has two different modes `Service View` and `Component View`:\n\n- `Component View` - You will see this when you access a specific Component in the Catalog.\n- `Service View` - You will see this when you access the `DORA Metrics` sidebar navigation.\n\nHere are some examples:\n\n| Component View                                                                                                                 | Service View                                                                                                                   |\n| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |\n| ![Metrics](https://raw.githubusercontent.com/liatrio/backstage-dora-plugin/main/screenshots/ranked/tab.png?raw=true 'Metrics') | ![Trend](https://raw.githubusercontent.com/liatrio/backstage-dora-plugin/main/screenshots/trend/teamView.png?raw=true 'Trend') |\n\n## Dependencies\n\nThis plugin relies on the following dependencies:\n\n- [Liatrio DORA React Components](https://github.com/liatrio/react-dora-charts)\n- [Liatrio OTel Collector](https://github.com/liatrio/liatrio-otel-collector)\n- An instance of Loki DB\n  - **You can swap out for any Time Series DB, but you will need to fork and modify the [Liatrio DORA API](https://github.com/liatrio/liatrio-dora-api) to do so**\n- A GitHub Organization hosting your repositories\n  - **We will expand this to more platforms in the future**\n\n## Installation of Dependencies\n\n### Docker Compose\n\nIn the `dependencies` folder, you will find a docker-compose file. Using this will spin up the following in docker containers:\n\n- An instance of Loki DB with persistent storage\n- An instance of Promtail, which is required by Loki DB\n- An instance of an OTel Collector configured to accept events from GitHub\n- An instance of the [Liatrio DORA API](https://github.com/liatrio/liatrio-dora-api), which this plugin can call to get the data it needs\n\nYou will need to update the `.env` file with your `GitHub Org`, `User` and `PAT` (with full repo access) for the API to be able to return a list of services\n\n### Kubernetes\n\nIf you have a Kubernetes Cluster, we have a quick start guide that installs `Loki DB` and [Liatrio OTel Collector](https://github.com/liatrio/liatrio-otel-collector) (among a few other tools) that can be found [here](https://github.com/liatrio/tag-o11y-quick-start-manifests)\n\nThis quick start manifest does not set up the [Liatrio DORA API](https://github.com/liatrio/liatrio-dora-api) or any other API which you would need to sit between this plugin and the Loki DB.\n\n### Configuring GitHub\n\nOnce you have the dependencies configured and running, you will need to update your GitHub Organization to send events to the OTel Collector.\n\nYou can do this by setting up a new `Webhook` and configuring the `Webhook` to send the following events:\n\n- Deployments\n- Issues\n- Pull Requests\n- Deployment Statuses\n\n## Installation into Backstage\n\nTo Install this plugin you'll need to do the following:\n\n1. Install the `@liatrio/backstage-dora-plugin` package into the `/packages/app` folder\n\n   ```shell\n   npm install @liatrio/backstage-dora-plugin\n\n   yarn add @liatrio/backstage-dora-plugin\n   ```\n\n2. Update the `/packages/app/src/App.tsx` file:\n\n   - Add this to your imports:\n\n   ```typescript\n   import { EntityDORACharts } from '@liatrio/backstage-dora-plugin';\n   ```\n\n   - Add this into the `FlatRoutes` element as a child:\n\n   ```typescript\n   \u003cRoute path=\"/dora\" element={\u003cEntityDORACharts showServiceSelection /\u003e} /\u003e\n   ```\n\n3. Update the `/packages/app/src/components/catalog/EntityPage.tsx` file:\n\n   - Add this to your imports:\n\n   ```typescript\n   import {\n     EntityDORACharts,\n     EntityDORAAtAGlance,\n   } from '@liatrio/backstage-dora-plugin';\n   ```\n\n   - Define this constant:\n\n   ```typescript\n   const doraContent = (\n     \u003cGrid container spacing={3} alignItems=\"stretch\"\u003e\n       {entityWarningContent}\n       \u003cEntityDORACharts showServiceSelection={false} /\u003e\n     \u003c/Grid\u003e\n   );\n   ```\n\n   - Add this into the `serviceEntityPage`, `websiteEntityPage`, `defaultEntityPage` `EntityLayoutWrapper` elements:\n\n   ```typescript\n   \u003cEntityLayout.Route path=\"/dora\" title=\"DORA\"\u003e\n     {doraContent}\n   \u003c/EntityLayout.Route\u003e\n   ```\n\n   - Add this into the `overviewContent` `Grid`:\n\n   ```typescript\n   \u003cGrid item md={6}\u003e\n     \u003cEntityDORAAtAGlance /\u003e\n   \u003c/Grid\u003e\n   ```\n\n4. Update the `app-config.yaml`:\n\n   - Add this to the `proxy.endpoints` and use the correct URL for your API:\n\n   ```yaml\n   /dora/api:\n     target: [URL_TO_DORA_API]\n   ```\n\n   - Add this root property `dora` to the file and then add the following under it:\n\n     - Required:\n\n       - `dataEndpoint`: This the endpoint on the proxy that provides the deployment data. If you are using the `liatrio-dora-api` this will be `data`\n       - `serviceListEndpoint`: This the endpoint on the proxy that provides the service and repo ownership data. If you are using the `liatrio-dora-api` this will be `services`\n       - `daysToFetch`: This is the number of days worth of data that will be fetched for the charts to have available for display\n\n     - Optional:\n\n       - `showWeekends`: This boolean will toggle the `Deployment Frequency Chart` to hide weekends or show them. The default is to hide them.\n       - `includeWeekends`: This boolean will toggle whether weekends are included in scoring your `Deployment Frequency` and `Change Lead Time`. The default is to exclude them.\n       - `showDetails`: This boolean will toggle whether or not the `DORA At a Glance` shows the exact scores on hover or as static text. The default is to show them on hover.\n       - `showTrendGraph`: Enabling this field will change the `DORA At a Glance` to be a Trend Graph rather than have Metric indicators\n       - `showIndividualTrends`: Enabling this field will add individual Metric Trends to the Trend Graph in the `DORA At a Glance` component\n       - `rankThresholds`: This is an object to override the default rank thresholds for DORA Score Board and is fully optional all the way down to the individual ranks.\n\n         There are 4 scores, all are optional:\n\n         - `deployment_frequency` measured in hours\n         - `change_lead_time` measured in hours\n         - `change_failure_rate` measured as a percentage\n         - `recover_time` measured in hours\n\n         Each score has the following rank options:\n\n         - `elite`\n         - `high`\n         - `medium`\n\n         **Note: Anything outside `medium` is considered `low`**\n\n         The default rank thresholds are:\n\n         - deployment_frequency\n           - elite: 24 (1 day or less)\n           - high: 168 (1 week or less)\n           - medium: 720 (1 month or less)\n         - change_lead_time\n           - elite: 24 (1 day or less)\n           - high: 168 (1 week or less)\n           - medium: 720 (1 month or less)\n         - change_failure_rate\n           - elite: 5\n           - high: 10\n           - medium: 45\n         - recover_time\n           - elite: 1 (1 hr or less)\n           - high: 24 (1 day or less)\n           - medium: 168 (1 week or less)\n\n## Contributing\n\nSee [Contributing](./CONTRIBUTING) to Backstage Dora Plugin\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliatrio%2Fbackstage-dora-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliatrio%2Fbackstage-dora-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliatrio%2Fbackstage-dora-plugin/lists"}