@c2l2c/backstage-plugin-dora-metrics

A Backstage frontend plugin that surfaces DORA metrics per catalog entity — scoped to the specific service you're viewing, not your whole org.

For each catalog service annotated with a GitHub repo, this plugin adds a DORA Metrics tab that computes all four key metrics directly from GitHub PRs via OAuth — no extra backend or data pipeline required:

• Deployment Frequency — how often PRs are merged to the target branch
• Lead Time for Changes — average time from PR open to merge
• Change Failure Rate — percentage of deployments that were hotfixes (production only)
• MTTR — mean time to recover, measured as average hotfix PR duration (production only)
• Hotfixes to Production - number of hotfixes deployed to production in the given time period (production only)

Ratings are classified as Elite / High / Medium / Low per DORA research benchmarks.

How this differs from org-level DORA scorecards

Org-level DORA plugins aggregate metrics across all repositories in your GitHub org. This plugin instead scopes metrics to a single catalog entity — useful when you want to track DORA health at the service level, compare environments (e.g. production vs staging), or drill into which specific PRs are driving your lead time or failure rate. It also requires no backend: all data is fetched client-side using the user's existing GitHub OAuth session.

Screenshots/Videos

1. DORA metrics dashboard

2. Deployment frquency exapnded view

3. LTFC expanded view

4. CFR expanded view

5. MTTR expanded view

Requirements

• Backstage v1.35+ (new frontend system)
• GitHub OAuth configured in your Backstage instance (the plugin uses githubAuthApi to call the GitHub REST API)
• Catalog entities annotated with github.com/project-slug: org/repo

Installation

# In your Backstage app workspace
yarn workspace app add @c2l2c/backstage-plugin-dora-metrics

Register the plugin

In packages/app/src/App.tsx:

import doraMetricsPlugin from '@c2l2c/backstage-plugin-dora-metrics/alpha';

// Add to your app's plugins array
const app = createApp({
  plugins: [doraMetricsPlugin],
  // ...
});

Configuration

Add to your app-config.yaml:

app:
  doraMetrics:
    # Lookback window in days (default: 30)
    collection:
      initialDays: 30

    # Define the environments / branches to track.
    # Exactly ONE environment may set isProduction: true.
    environments:
      - name: Production
        branch: main             # single branch name
        isProduction: true
        label: hotfix            # PR label for production failures (used for CFR/MTTR)
      - name: Staging
        branch: staging
        isProduction: false
      - name: Any main
        # Comma-separated list — PRs merged to any of these branches are included
        branch: "main,master"
        isProduction: false
      - name: Release branches
        # JavaScript regex — resolved against the repo's actual branch list at query time
        branch: "^release/.*"
        isProduction: false

    # Optional: override DORA benchmark targets
    targets:
      deploymentFrequency: 1   # deploys per day (Elite ≥ 1)
      leadTime: 24             # hours (Elite ≤ 24h)
      changeFailureRate: 5     # % (Elite ≤ 5%)
      mttr: 1                  # hours (Elite ≤ 1h)

    # Optional: enable mock data for local development (skips GitHub API calls)
    debug: false

Branch and label patterns

Both the branch and label fields accept the same three formats:

| Format | Example | Behaviour | |--------|---------|-----------| | Single name | main / hotfix | Exact match | | Comma-separated | main,master / hotfix,fix,bug | Matches any name in the list | | JavaScript regex | ^release/.* / ^hotfix | Regex test against each value |

A string is treated as a regex if it contains any of these characters: | ^ $ [ ] ( ) { } ? + * \

For branch: when multiple branches match, PRs are fetched from all of them and deduplicated by PR number. Regex patterns are resolved against the repo's live branch list via the GitHub Branches API at query time.

For label: a PR is classified as a hotfix if any of its GitHub labels match the pattern.

Environment constraints

• You may define any number of environments.
• Exactly one environment may have isProduction: true. The plugin throws a configuration error at startup if this constraint is violated.
• Change Failure Rate, MTTR, and Hotfixes to Production are only calculated for the production environment.

Per-repo overrides via catalog annotations

You can override environments and targets on a per-service basis in catalog-info.yaml without changing the global config:

metadata:
  annotations:
    github.com/project-slug: my-org/my-repo

    # Override the environments list for this repo only (JSON)
    dora-metrics/environments: |
      [
        { "name": "Production", "branch": "main", "isProduction": true, "label": "hotfix" },
        { "name": "Staging",    "branch": "staging", "isProduction": false }
      ]

    # Override DORA targets for this repo only (JSON, partial overrides supported)
    dora-metrics/targets: |
      { "deploymentFrequency": 2, "leadTime": 48 }

Annotation values are parsed as JSON. Partial targets overrides are merged with the global targets — only the keys you specify are replaced.

Example configs

Ready-to-use example configs are in the examples/ directory:

| File | Description | |------|-------------| | app-config.regex-branch.yaml | Production tracked with a regex branch pattern (^release/.*) and a comma-separated label pattern | | app-config.multi-branch.yaml | Production tracked across main,master; staging across develop,dev; hotfix label as regex | | catalog-info.yaml | Per-repo environment and target overrides via catalog-info.yaml annotations |

How it works

The plugin reads the github.com/project-slug annotation from the catalog entity and calls the GitHub REST API (authenticated via the user's GitHub OAuth session) to fetch merged pull requests within the configured time window.

It calculates:

• Deployment Frequency: merged PRs per day to the target branch
• Lead Time: time from PR creation to merge
• CFR: percentage of PRs labelled as hotfixes (production environments only)
• MTTR: average time hotfix PRs were open (production environments only)
• Hotfixes to Production - number of hotfixes deployed to production in the given time period (production environments only)

License

Apache-2.0