Enable DORA metrics for CloudBees CI and Jenkins pipelines

Configure CloudBees Unify and your CloudBees CI or Jenkins Multibranch Pipeline to populate the DORA metrics dashboard with deployment frequency, lead time for changes, change failure rate, and mean time to recovery (MTTR) data. This guide covers both the CloudBees Unify platform configuration and the Jenkinsfile changes required to report build and deployment events.

Before you begin, ensure you have:

An Admin role in CloudBees Unify, or a custom role with permissions to manage Integrations, Environments, and Components, and to view Analytics.
CloudBees CI 2.555.1.36485+ with the CloudBees Unify Integration :: Controllers plugin v1.1615 or later installed.
Jenkins: install the CloudBees Unify Integration :: Controllers plugin, and ensure your Jenkins and plugin versions meet the requirements in CI and Jenkins integration reference.
An SCM integration (GitHub, GitLab, or Bitbucket) connected to CloudBees Unify, required before you can create a component.
An active Multibranch Pipeline with at least one recent build.
Outbound HTTPS from your CI controller to the required CloudBees Unify hostnames. Refer to Configure network security policies for the full list.

Configure CloudBees Unify for deployment tracking

Three platform-side resources must exist before CloudBees CI or Jenkins can report deployments to CloudBees Unify: a CI integration, a component linked to your repository, and at least one environment. Create all three in CloudBees Unify before modifying your Jenkinsfile.

Connect your CI controller

The CI integration authorizes your CloudBees CI or Jenkins controller to send build and deployment data to CloudBees Unify.

Create the integration in CloudBees Unify under Category: Continuous integration, selecting CloudBees CI controller or Jenkins® controller, then approve the connection from your controller. Refer to Connect a single controller with approval for the full connection steps, additional connection methods (CasC, PEM file, operations center), and troubleshooting.

Create a component for your repository

Connecting the CI integration alone does not create a component. The DORA metrics dashboard remains empty until a component exists and is linked to the repository used by your pipeline.

To create a component:

Navigate to Components and select Create component.
Search for and select your repository.
Verify the target organization and select Create components.

The component appears in your components list. The repository associated with the component must match the repository used by your CI integration for deployment data to flow correctly.

Create an environment

Environments represent the deployment targets that CloudBees Unify tracks. The targetEnvironment value in your Jenkinsfile must exactly match the name you create here.

To create an environment:

Navigate to Configurations Environments and select Create environment.
Enter an environment name, for example Production.
Select Save.

Repeat for any additional environments you want to track, such as Staging or Development.

The Requires approval and Properties and secrets fields are not required for DORA metrics tracking.

Instrument your Jenkins pipeline

Two Groovy steps provided by the CloudBees Unify Integration :: Controllers plugin report build and deployment data to CloudBees Unify. Both steps belong in the same Jenkinsfile: registerBuildArtifactMetadata runs during the build stage and registerDeployedArtifactMetadata runs during the deployment stage. The first step returns an artifact ID that you pass to the second.

Register the build artifact

registerBuildArtifactMetadata records a build output in CloudBees Unify and returns an artifact ID. Add this step to the post { success { … } } block of your build or package stage, and capture the returned value in env.ARTIFACT_ID for use in the deployment step.

post {
    success {
        script {
            env.ARTIFACT_ID = registerBuildArtifactMetadata(
                name: "my-app",
                url: "${BUILD_URL}artifact/my-app-${BUILD_NUMBER}.tar.gz",
                version: "${BUILD_NUMBER}",
                type: "Binary"
            )
        }
    }
}▼

The step returns a UUID string. Store it as env.ARTIFACT_ID so it is available to downstream stages. If you do not capture the return value, the deployment step has no artifact to reference.

For the full parameter specification, refer to Register CI build artifacts.

Register the deployed artifact

registerDeployedArtifactMetadata records that the artifact was deployed to a named environment. This is the step that drives DORA metrics. Add this step to the post { always { … } } block of your deployment stage.

post {
    always { (1)
        script {
            registerDeployedArtifactMetadata(
                artifactId: env.ARTIFACT_ID,
                targetEnvironment: "Production", (2)
                allowNoMatchingComponent: false (3)
            )
        }
    }
}▼

1	Use `always` rather than `success` so that failed deployments are also recorded. Without this, failed deployments are not recorded and change failure rate and MTTR do not populate.
2	Replace `"Production"` with the exact environment name you created in CloudBees Unify.
3	Set `allowNoMatchingComponent: false` so the step fails loudly if no CloudBees Unify component matches the artifact’s repository, rather than silently registering an orphaned deployment.

For the full parameter specification, refer to Register CI deployed artifacts.

Verify DORA metrics are populating

After your pipeline runs with both steps in place, verify that data has reached CloudBees Unify before reviewing the DORA metrics dashboard.

Review the Jenkins console output and confirm that both steps logged success and printed an artifact ID.
In CloudBees Unify, navigate to your component and select the Environment inventory tab. Confirm the artifact version appears in the Production column with a deployment timestamp.
Navigate to Analytics Software delivery activity and confirm the successful deployments count has increased.
Navigate to Analytics DORA metrics, select FILTER, and set Environment to Production and Duration to Last 7 days or Last 30 days. Select APPLY.

Allow 10 to 15 minutes after a pipeline run for data to be processed. Deployment frequency and lead time become meaningful after 5 to 10 deployments over multiple days. Change failure rate and MTTR require production incidents to be tracked and linked to deployments.

Troubleshoot

The following describes common issues when DORA metrics data does not appear or is incomplete.

DORA metrics dashboard is empty despite a connected CI integration

A component has not been created for the repository.

Create a component. Refer to Create a component for your repository.
Trigger a pipeline run.
Allow 2 to 3 minutes for data to appear.

Deployment data is missing from the dashboard

The registerDeployedArtifactMetadata step did not run, or the targetEnvironment value does not exactly match a configured environment name.

Review the pipeline console output and confirm the step completed successfully.
Navigate to Configurations Environments and verify the environment name matches the value in your Jenkinsfile.

Change failure rate and MTTR show no data

The registerDeployedArtifactMetadata step is in a post { success { … } } block rather than post { always { … } }, so failed deployments are not being recorded. Move the step to an always block.

Metric calculations are incomplete

Insufficient deployment history exists for accurate calculations. Confirm the pipeline ran successfully in recent builds, allow 10 to 15 minutes for processing, and aim for 5 to 10 or more deployments before drawing conclusions from the data.

allowNoMatchingComponent: false causes the pipeline step to fail

No CloudBees Unify component matches the artifact’s repository. Create or verify the component mapping before running the deployment stage again. Refer to Create a component for your repository.