--- title: "Setting up DORA metrics" canonical_url: "https://docs.getdx.com/reports/dora-metrics/" md_url: "https://docs.getdx.com/reports/dora-metrics.md" last_updated: "2026-06-18" --- # 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 ### Self-reported DORA Use self-reported DORA metrics when you want to start before system instrumentation is complete. DX collects these metrics through snapshots using DORA-aligned questions. | Metric | Definition | | ----------------------------------- | ---------------------------------------------------------------------------- | | **Lead time for changes** | Time from committing code to trunk to it successfully running in production. | | **Deploy frequency** | How often code is deployed to production or released to end users. | | **Change fail percentage** | Percentage of changes that cause degraded service, outages, or incidents. | | **Failed deployment recovery time** | Time taken to restore service after a failed deployment or release. | ### System-based DORA Use system-based DORA metrics when you want DX to calculate reports from engineering systems. System-based setup requires source control, production deployment, incident, and service ownership data. | Report | What it measures | | -------------------------- | ----------------------------------------------------- | | **Deploy frequency** | Number of production deployments over time. | | **Open to deploy** | Time from pull request open to deployment. | | **Merge to deploy** | Time from pull request merge to deployment. | | **Commit to deploy** | Time from default branch commit to deployment. | | **Change fail percentage** | Number of incidents divided by number of deployments. | | **Time to recover** | Average time to resolve incidents. | 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?](https://docs.getdx.com/knowledgebase/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`](https://docs.getdx.com/datacloudapi/methods/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](https://docs.getdx.com/connectors/github-deployments/). Review catalog services after import because services may be generated from repository names. | | [Deploy rules](https://docs.getdx.com/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](https://docs.getdx.com/connectors/?category=CI%2FCD). 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`](https://docs.getdx.com/datacloudapi/methods/deployments.create/#arguments) so DX attributes the deployment to the specific pull requests included. If a pull request can affect multiple services, call [`deployments.setPullServices`](https://docs.getdx.com/datacloudapi/methods/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`](https://docs.getdx.com/datacloudapi/methods/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](https://app.getdx.com/catalog?type=service). ## 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`](https://docs.getdx.com/webapi/methods/catalog.entities.upsert/) before sending DORA data. For detailed guidance, see [How should I set up the DX catalog for DORA metrics?](https://docs.getdx.com/knowledgebase/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](https://app.getdx.com/catalog?type=service) 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](https://app.getdx.com/catalog?type=service) with the expected identifier. 1. Confirm recent production deployments appear for that service. 1. Open a recent deployment and confirm the expected pull requests or commits are attributed. 1. For monorepos, confirm unrelated pull requests are not attributed to the service deployment. 1. Confirm incident records use the same service identifier or a mapped alias. 1. Confirm the service has the expected team owner. 1. Review the DORA reports for that service and team after data import completes. 1. 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. --- ## Sitemap [Overview of all docs pages](/llms.txt)