@syafiqizzaud/backstage-gitlab-plugin-dora-metrics

A Backstage frontend plugin that surfaces DORA metrics per catalog entity, scoped to the specific service you're viewing — backed by GitLab merge requests, no extra backend or data pipeline required.

For each catalog entity annotated with a GitLab project, this plugin adds a DORA Metrics tab that computes all four key metrics directly from GitLab MRs:

• Deployment Frequency — how often MRs are merged to the target branch
• Lead Time for Changes — average time from MR open to merge
• Change Failure Rate — percentage of deployments that were hotfixes (production only)
• MTTR — mean time to recover, measured as average hotfix MR duration (production only)

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

Requirements

• Backstage v1.35+ (new frontend system)
• GitLab accessible from the Backstage backend
• Catalog entities annotated with gitlab.com/project-id and gitlab.com/instance

Installation

yarn workspace app add @syafiqizzaud/backstage-gitlab-plugin-dora-metrics

Register the plugin in packages/app/src/App.tsx:

import doraMetricsPlugin from '@syafiqizzaud/backstage-gitlab-plugin-dora-metrics';

const app = createApp({
  features: [
    // ...existing features
    doraMetricsPlugin,
  ],
});

GitLab API access — two modes

The plugin needs to call the GitLab REST API. Choose the mode that matches your Backstage setup.

Mode 1 — Immobiliare Labs backend plugin (default, no extra config)

If you already have @immobiliarelabs/backstage-plugin-gitlab-backend installed, no additional configuration is needed. The plugin automatically uses its /api/gitlab/rest/{instance}/ proxy endpoint.

The gitlab.com/project-id and gitlab.com/instance annotations are also auto-filled by its GitlabFillerProcessor, so entities are ready out of the box.

Mode 2 — Plain proxy (no Immobiliare Labs plugin required)

If you are not using the Immobiliare Labs plugin, configure a standard Backstage proxy and set gitlabProxyPath:

app-config.yaml:

proxy:
  endpoints:
    '/gitlab/api':
      target: https://gitlab.your-company.com/api/v4
      headers:
        PRIVATE-TOKEN: ${GITLAB_TOKEN}

app:
  doraMetrics:
    gitlabProxyPath: /gitlab/api   # path after /api/proxy

You will also need to add gitlab.com/project-id and gitlab.com/instance annotations to your catalog entities manually or via a custom processor.

Configuration

Add to app-config.yaml under app.doraMetrics:

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

    # For plain proxy mode only — omit if using Immobiliare Labs backend
    # gitlabProxyPath: /gitlab/api

    # Environments / branches to track.
    # Exactly ONE environment may set isProduction: true.
    environments:
      - name: Production
        branch: main
        isProduction: true
        label: hotfix        # MR label used to identify hotfixes (CFR / MTTR)
      - name: Staging
        branch: staging
        isProduction: false
      - name: Development
        branch: development
        isProduction: false

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

Branch and label patterns

Both branch and label fields accept three formats:

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

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

For branch: when a regex matches multiple branches, MRs are fetched from all of them and deduplicated by MR number.

For label: an MR is classified as a hotfix if any of its GitLab labels match the pattern.

Per-entity annotation overrides

Override environments and targets for a specific service in its catalog-info.yaml:

metadata:
  annotations:
    gitlab.com/project-slug: my-group/my-repo

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

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

Partial dora-metrics/targets overrides are merged with the global targets — only the keys you specify are replaced.

How it works

The plugin reads the gitlab.com/project-id and gitlab.com/instance annotations from the catalog entity and calls the GitLab MRs API, paginating through all results within the configured time window.

It calculates:

• Deployment Frequency: merged MRs per day to the target branch
• Lead Time: average time (hours) from MR creation to merge
• CFR: percentage of MRs labelled as hotfixes (production environments only)
• MTTR: average duration (hours) of hotfix MRs (production environments only)

Change Failure Rate and MTTR are only computed for environments with isProduction: true.

Environment constraints

• Any number of environments may be defined.
• Exactly one environment may have isProduction: true.
• CFR, MTTR, and hotfix count are only shown for the production environment.

License

Apache-2.0