feat: add DevLake DORA Metrics plugin

[mikilior]

DevLake DORA Metrics Plugin

Closes #8189

Why this plugin matters

Engineering teams today face a fundamental challenge: measuring what actually matters. Lines of code, story points, and velocity tell you how busy a team is — not how effective it is. The DORA research program, backed by over a decade of data from thousands of engineering organizations, identified four metrics that reliably predict both software delivery performance and organizational outcomes:

Metric	What it measures
Deployment Frequency	How often code reaches production
Lead Time for Changes	Time from commit to production
Change Failure Rate	Percentage of deployments causing incidents
Mean Time to Recovery	How fast teams recover from failures

Elite-performing teams don't just ship faster — they ship with higher quality, lower burnout, and better business outcomes. DORA metrics give engineering leadership an objective, evidence-based language for that conversation.

The gap, however, is access. Most teams collect the raw data — in CI/CD systems, Git providers, and incident trackers — but it lives in silos. Making sense of it requires either expensive tooling or significant engineering investment.

Apache DevLake solves the collection and normalization problem: it ingests data from GitHub, GitLab, Jenkins, PagerDuty, Jira, and more into a unified domain model, and computes DORA metrics out of the box. It is 100% open-source, CNCF-incubating, and production-ready.

This plugin brings those metrics directly into Backstage — the developer portal where engineers already spend their time. Instead of opening a separate Grafana dashboard, teams can see DORA performance at a glance: on a dedicated metrics page, and inline on every service's entity page. It closes the feedback loop between the software catalog and engineering effectiveness data, making DORA metrics a first-class citizen in the inner loop of development.

---

Packages

Package	Role
@backstage-community/plugin-devlake	Frontend plugin
@backstage-community/plugin-devlake-backend	Backend plugin
@backstage-community/plugin-devlake-common	Shared types and DORA classification logic

---

Features

DoraMetricsPage — a full standalone dashboard page:

• Team selector (driven by app-config.yaml)
• Time range presets: 7D, 30D, 90D, Quarter, 1Y + custom date picker
• Four metric cards: Deployment Frequency, Lead Time for Changes, Change Failure Rate, MTTR
• DORA level badges (Elite / High / Medium / Low) with color coding
• Trend line charts per metric
• "All teams" aggregate view

EntityDoraCard — a compact card for entity pages:

• Annotate any entity with devlake.io/project-name to show its DORA metrics inline
• 2×2 grid of metrics with DORA level chips
• Optional Grafana deep-link per entity (configurable via devlake.grafana.baseUrl)
• Falls back to MissingAnnotationEmptyState when the annotation is absent

Both components support the New Frontend System extension points via the /alpha entry point (EntityCardBlueprint, PageBlueprint, ApiBlueprint) — no manual route registration in App.tsx is required.

---

Technical Design

Why direct MySQL instead of the DevLake REST API?

DevLake v1.x exposes a Grafana-style dashboard API but no DORA REST endpoint suitable for programmatic consumption. The backend plugin queries DevLake's MySQL domain-layer tables directly with read-only credentials. This is the same data source Grafana uses.

Backend data flow

Backstage backend
  └─ devlake-backend plugin
       └─ DevlakeDbClient (mysql2/promise, read-only pool)
            └─ DevLake MySQL DB (domain layer tables)

The backend exposes three endpoints under /api/devlake:

Endpoint	Description
GET /health	Liveness check
GET /teams	Returns configured teams + synthetic "All" entry
GET /dora/metrics?team=&preset=	Returns all 4 DORA metrics for the given team and time range
GET /dora/metrics/trend?team=&preset=	Returns daily trend data points for charting

Time range can be specified as a preset (7d, 30d, 90d, quarter, 1y) or explicit from/to date strings. team=All queries across all projects.

Key domain tables queried

Table	Used for
cicd_deployment_commits	Deployment Frequency, Change Failure Rate
project_mapping	Joining scopes/repos to projects
pull_requests + project_pr_metrics	Lead Time for Changes (median PR cycle time)
incidents + project_incident_deployment_relationships	Change Failure Rate, MTTR

DORA level thresholds

Metric	Elite	High	Medium	Low
Deployment Frequency	≥1/day	≥1/week	≥1/month	<1/month
Lead Time	<1h	<1 day	<1 week	≥1 week
Change Failure Rate	<5%	<10%	<15%	≥15%
MTTR	<1h	<1 day	<1 week	≥1 week

Frontend architecture

DoraMetricsPage / EntityDoraCard
  └─ DevlakeApi (ApiRef)
       └─ DevlakeClientImpl
            └─ Backstage discovery API → /api/devlake/*

---

Installation

1. Add the packages

yarn --cwd packages/app add @backstage-community/plugin-devlake
yarn --cwd packages/backend add @backstage-community/plugin-devlake-backend

2. Register the backend plugin

// packages/backend/src/index.ts
backend.add(import('@backstage-community/plugin-devlake-backend'));

3. Configure app-config.yaml

devlake:
  baseUrl: http://localhost:4000

  db:
    host: ${DEVLAKE_DB_HOST}
    port: 3306
    user: ${DEVLAKE_DB_USER}
    password: ${DEVLAKE_DB_PASSWORD}
    database: devlake
    ssl: true

  teams:
    - name: Platform
      devlakeProjectName: platform-backend   # must match the project name in DevLake
    - name: Mobile
      devlakeProjectName: mobile-app

  # Optional: deep-link entity cards to a Grafana DORA dashboard
  grafana:
    baseUrl: https://grafana.example.com
    doraDashboardPath: /d/qNo8_0M4z/dora    # default, can be omitted

Note: devlakeProjectName must exactly match the project name in DevLake (visible under Projects in the DevLake UI). It is separate from the display name shown in Backstage.

4a. Legacy system — add the page route

// packages/app/src/App.tsx
import { DoraMetricsPage } from '@backstage-community/plugin-devlake';

<Route path="/devlake" element={<DoraMetricsPage />} />

4b. New Frontend System — no route registration needed

import devlakePlugin from '@backstage-community/plugin-devlake/alpha';
// add to your app's features array

5. Add EntityDoraCard to entity pages

Legacy system:

import { EntityDoraCard, isDevlakeAvailable } from '@backstage-community/plugin-devlake';

<EntitySwitch>
  <EntitySwitch.Case if={isDevlakeAvailable}>
    <Grid item md={4}>
      <EntityDoraCard />
    </Grid>
  </EntitySwitch.Case>
</EntitySwitch>

New Frontend System: the entityDoraCard extension from /alpha is auto-registered — no entity page changes required.

6. Annotate entities

# catalog-info.yaml
metadata:
  annotations:
    devlake.io/project-name: platform-backend

---

Test plan

• yarn tsc passes with no errors
• 81 tests across 12 suites — all passing
  • Backend: 17 tests (router, DevlakeDbClient, config parsing)
  • Frontend: 60 tests (API client, all components, EntityDoraCard, DoraMetricsPage)
  • Common: 4 tests (DORA classification thresholds)
• DoraMetricsPage renders at /devlake with a running DevLake instance
• EntityDoraCard renders on an annotated entity
• EntityDoraCard shows MissingAnnotationEmptyState when annotation is absent

[backstage-goalie]

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@backstage-community/plugin-devlake-backend	workspaces/devlake/plugins/devlake-backend	minor	v0.1.0
@backstage-community/plugin-devlake-common	workspaces/devlake/plugins/devlake-common	minor	v0.1.0
@backstage-community/plugin-devlake	workspaces/devlake/plugins/devlake	minor	v0.1.0