Enable DORA metrics for GitHub Actions workflows

Configure CloudBees Unify and your GitHub Actions workflows 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 workflow file 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.
Organization owner or admin access on GitHub, required to install the CloudBees GitHub App.
An active repository with GitHub Actions workflows running.
An SCM integration (GitHub, GitLab, or Bitbucket) connected to CloudBees Unify, required before you can create a component.

Configure CloudBees Unify for deployment tracking

Three platform-side resources must exist before GitHub Actions can report deployments to CloudBees Unify: a GitHub App integration, a component linked to your repository, and at least one environment. Create all three in CloudBees Unify before modifying your workflow files.

Connect the GitHub App integration

The GitHub App integration authorizes CloudBees Unify to receive build and deployment data from your GitHub Actions workflows.

To connect the GitHub App:

Navigate to Configurations Integrations and select Create integration.
Select GitHub App.
Select Install GitHub App and authorize the app on GitHub against the organization or account that owns your repository.

Select the repository scope.

Selecting Selected repositories rather than All repositories is recommended when setting up for the first time, so you can verify data is flowing correctly for a specific repository before expanding the integration’s scope.

The integration appears in your integrations list when authorization is complete.

Create a component for your repository

Connecting the GitHub App 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 workflows.

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 connected via the GitHub App for deployment data to flow correctly.

Create an environment

Environments represent the deployment targets that CloudBees Unify tracks. The target-environment value in your workflow file 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.

Instrument your GitHub Actions workflow

Two CloudBees-provided actions report build and deployment data to CloudBees Unify. Both actions belong in the same workflow: cloudbees-io-gha/register-build-artifact@v3 runs in the build job and cloudbees-io-gha/register-deployed-artifact@v1 runs in the deploy job. The first action outputs an artifact ID that you pass to the second via a job output.

Register the build artifact

register-build-artifact@v3 records a build output in CloudBees Unify and outputs an artifact ID as cbp_artifact_id. Add this step to your build job and expose the output at the job level so the deploy job can reference it.

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact_id: ${{ steps.register-artifact.outputs.cbp_artifact_id }}
    steps:
      - uses: actions/checkout@v4
      - name: Register build artifact
        id: register-artifact
        uses: cloudbees-io-gha/register-build-artifact@v3
        with:
          artifact-name: "my-app-${{ github.sha }}"
          artifact-version: "${{ github.sha }}"
          artifact-type: "docker-image"▼

Two details are required for the artifact ID to reach the deploy job:

The step must have an id (in this example, register-artifact) so its output can be referenced as steps.register-artifact.outputs.cbp_artifact_id.
The job must declare an outputs: entry that maps a name of your choice to that step output. The deploy job consumes it through needs.build.outputs.<name>.

Register the deployed artifact

register-deployed-artifact@v1 records that the artifact was deployed to a named environment. This is the action that drives DORA metrics. Add this step to your deploy job with if: always() so that failed deployments are also recorded.

  deploy:
    runs-on: ubuntu-latest
    needs: build (1)
    steps:
      - name: Register deployed artifact
        if: always() (2)
        uses: cloudbees-io-gha/register-deployed-artifact@v1
        with:
          artifact-id: ${{ needs.build.outputs.artifact_id }}
          target-environment: Production (3)▼

1	Required. If not specified, GitHub Actions does not make the build job’s outputs available to the deploy job, and the artifact ID cannot be passed between them.
2	Records failed deployments. If not specified, failed deployments are not recorded and change failure rate and MTTR do not populate.
3	Replace `Production` with the exact environment name you created in CloudBees Unify.

Verify DORA metrics are populating

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

In the GitHub Actions tab, confirm the workflow run completed and both the register-artifact and register-deployed-artifact steps succeeded.
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 workflow 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 GitHub App integration

A component has not been created for the repository.

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

Deployment data is missing from the dashboard

The register-deployed-artifact step did not run, or the target-environment value does not exactly match a configured environment name.

Review the workflow run in the GitHub Actions tab and confirm the step completed successfully.
Navigate to Configurations Environments and verify the environment name matches the value in your workflow file.

Change failure rate and MTTR show no data

The register-deployed-artifact step is missing if: always(), so failed deployments are not being recorded. Add if: always() to the step.

The deploy job cannot access the artifact ID from the build job

The needs: build declaration is missing from the deploy job, or the build job does not declare a matching outputs: entry. Verify that the build job exposes cbp_artifact_id as a job-level output and that the deploy job declares needs: build.

Metric calculations are incomplete

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