Setting up DORA metrics

DX supports DORA metrics from self-reported snapshots and system data. Start with self-reported metrics when you need a fast baseline, then set up system-based DORA when you want reports based on source control, production deployments, incidents, and service ownership.

Choose your DORA setup path

The rest of this guide covers system-based DORA setup.

Before you begin

Have these inputs ready before you instrument system-based DORA metrics:

• Which source control connection contains the repositories you want to measure, such as GitHub, GitLab, Azure DevOps, Bitbucket, or Gerrit.
• How users are linked between DX and source control. Accurate user linking supports author-level DORA reports and helps DX assign default service owners. See How does DX link user identities across systems?.
• Which production service identifiers DX should use across deployment and incident data. If you already maintain a service catalog, define those services in DX before sending DORA data.
• Which development workflow each service uses, such as feature branches, integration branches, trunk-based development, or a monorepo.
• Which deployment orchestration each service uses, such as Argo CD, Jenkins, GitLab Pipelines, Octopus, GitHub Deployments, GitHub Actions, or another deployment tool.
• Which incident source contains production incidents, such as PagerDuty, Incident.io, FireHydrant, Opsgenie, Rootly, ServiceNow, Datadog Incident Management, Jira Service Management, or the DX API.

Step 1: Connect source control

Connect the source control system that contains the repositories you want to measure. DX uses source control data to connect deployments to pull requests, commits, authors, and repositories.

Pull request data powers Open to deploy and Merge to deploy. Default-branch commit data powers Commit to deploy for teams that use trunk-based development.

Step 2: Choose a deployment method

Choose the deployment ingestion method that matches how your organization records production deployments. Most customers should standardize on one method and use another only when a separate deployment system requires it.

Path	Use when	Notes
deployments.create	You have a custom workflow, monorepo, deployment source outside DX’s native connectors, or need precise attribution.	Recommended for most teams. This is the most flexible path and gives you the most control over service and pull request attribution.
Native deployment-event connectors	Your source control system already records production deployment events.	Use this when native deployment events are already clean and production environments are easy to identify. DX supports GitHub Deployments. Review catalog services after import because services may be generated from repository names.
Deploy rules	You need a no-code option that infers deployments from CI/CD workflow, pipeline, or stage runs.	Use as a last resort for complex implementations. Deploy rules use CI/CD data imported by connectors such as GitHub Actions, GitLab Pipelines, Bitbucket Pipelines, Azure DevOps Pipelines, Harness, Buildkite, CircleCI, and similar pipeline sources. They can create attribution issues or duplicate deployments in monorepos and custom release processes.

Avoid combining multiple deployment paths for the same service unless you intentionally deduplicate the data before it reaches DX.

Step 3: Set up deployment data

Deployment data is the most important part of system-based DORA setup. Your deployment method determines whether you send deployment events directly or configure DX to import or infer them.

For API-based setup, first decide how each production deployment should map to the pull requests or commits it shipped. Then send the fields DX needs to make that attribution:

• When production changed with deployed_at.
• Which service changed with service.identifier.
• Which code shipped with repository and commit_sha, or with merge_commit_shas when you already know the exact merge commits included in the deployment.

These fields are not all API-required fields, but DX needs them for accurate DORA attribution. Use integration_branch when pull requests merge into an integration branch before a release branch. Use source_url, source_name, and reference_id when you want easier troubleshooting and idempotent updates.

If you use native deployment-event connectors or deploy rules, configure them to capture production deployments only. Non-production deployments will skew Deploy frequency, lead-time, and failure-rate reports.

Step 4: Handle monorepos

Monorepos need explicit service attribution when pull requests can affect more than one service or when different services deploy independently.

If each pull request affects exactly one service, you can send deployments with merge_commit_shas so DX attributes the deployment to the specific pull requests included.

If a pull request can affect multiple services, call deployments.setPullServices when the pull request merges. This pre-associates the pull request with the services it changed, so later deployment events only count the pull request for the services that actually shipped.

Without this step, a service deployment can pick up unrelated pull requests that merged since the previous deployment. That usually shows up as inflated Deploy frequency or inaccurate Open to deploy and Merge to deploy numbers by service.

Step 5: Connect incidents

Incident data powers Change fail percentage and Time to recover. Connect an incident management tool when possible, or use incidents.upsert when incidents come from another source.

Deployment and incident records must use matching service identifiers for DX to connect failures to the right services. If your deployment source and incident tool use different names for the same service, map them with service aliases in the Catalog.

Step 6: Assign service ownership

DX uses service ownership to filter and aggregate DORA metrics by team. A service can have deployment and incident data, but team-level DORA views may be incomplete until ownership is assigned.

If you already maintain service ownership outside DX, create or update services with catalog.entities.upsert before sending DORA data. For detailed guidance, see How should I set up the DX catalog for DORA metrics?.

If DX creates services from deployment or incident data, update ownership later from the Catalog or the Catalog API.

Validate your setup

After you send data, validate one service before rolling the same pattern across every team.

1. Confirm the service exists in the Catalog with the expected identifier.
2. Confirm recent production deployments appear for that service.
3. Open a recent deployment and confirm the expected pull requests or commits are attributed.
4. For monorepos, confirm unrelated pull requests are not attributed to the service deployment.
5. Confirm incident records use the same service identifier or a mapped alias.
6. Confirm the service has the expected team owner.
7. Review the DORA reports for that service and team after data import completes.
8. If you use self-reported DORA, confirm the relevant snapshot questions are enabled and visible in snapshot reporting.

If the numbers look wrong, check deployment attribution first. Most DORA setup issues come from missing production deployments, duplicate deployment sources, mismatched service identifiers, or pull requests attributed to the wrong service.