Register CI deployed artifacts

Register deployed artifact metadata from your CloudBees CI or Jenkins® pipeline to CloudBees Unify to track artifact deployments across environments. Use deployment data to enable DORA metrics, environment inventory tracking, and deployment analytics.

Before you begin, ensure you have completed the CI or Jenkins integration and registered your build artifacts. For setup instructions, refer to Connect CI and Jenkins controllers. For artifact registration, refer to Register CI build artifacts.

Configure your Multibranch Pipeline to register deployed artifacts

To register deployed artifacts from your CI pipeline to CloudBees Unify:

Specify a registerBuildArtifactMetadata step in your Jenkinsfile that contains the required inputs listed in the table below:

Input name Data type Required? Description

name

String

Yes

The name of the artifact reported to CloudBees Unify.

url

String

Yes

The URL where the artifact version is located. For example, docker.io/myapp/myimg:1.0.0.

version

String

Yes

The version of the artifact to send to CloudBees Unify for artifact traceability purposes.

digest

String

The hash or checksum that uniquely identifies the artifact version.

CloudBees recommends specifying the digest to track artifact versions across repositories. For more information, refer to Artifact deployment and publish history.

label

String

A comma-separated list of artifact labels.

type

String

The type of artifact, such as Docker or Maven.

componentId

String

The ID of the component associated with the artifact. If not provided, the default value is the component ID where the CloudBees CI / Jenkins workflow is located.

commit

String

Only required if a different repository/branch.^[1]

The commit used to build the artifact. The default value is the commit hash from the CloudBees CI / Jenkins build.

commitUrl

String

Only required if a different repository/branch.^[1]

The URL of the commit used to build the artifact. The default value is the commit URL from the CloudBees CI / Jenkins build.

repositoryUrl

String

Only required if a different repository/branch.^[1]

The URL of the repository. The default value is the repository URL from the CloudBees CI / Jenkins build.

ref

String

Only required if a different repository/branch.^[1]

The branch or tag ref used to build the artifact. The default value is the ref from the CloudBees CI / Jenkins build.

^[1] By default, the artifact version is associated with the code commit from the CI build. If a different commit/repository/branch has been checked out for building the artifact, specify those commit details instead. If you do not want to associate commit details with this artifact version, omit this parameter.

Specify a registerDeployedArtifactMetadata step in your Jenkinsfile that contains the required inputs listed in the table below:

Table 2. Input details
Input name	Data type	Required?	Description
`artifactId`	String	No	The artifact’s ID, returned as the output value of the `registerBuildArtifactMetadata` step. For example, `def artifactId = registerBuildArtifactMetadata(…)`. Either this or `artifactUrl` must be present.
`artifactUrl`	String	No	URL of the deployed artifact. Either this or `artifactId` must be present.
`targetEnvironment`	String	Yes	The artifact’s target environment. The environment must already be configured in CloudBees Unify.
`labels`	String	No	Comma-separated labels attached to the artifact, for example `latest`.
`allowNoMatchingComponent`	Boolean	No	If set to `false` (the default), this step fails if the component is not registered in CloudBees Unify. If set to `true`, this step succeeds even if the component does not exist, logging the error instead.

Once you have registered build and deployed artifacts, this data is reflected in the DORA metrics dashboard and the environment inventory in Environments.

Usage examples

The following examples demonstrate common patterns for registering deployed artifact metadata.

Basic example using artifact ID

The following is a basic example of using the registerDeployedArtifactMetadata step with the artifact ID:

pipeline {
    agent any

    stages {
        stage('Registering deployed artifact') {
            steps {
                echo 'Registering the deployment metadata'
                registerDeployedArtifactMetadata(
                    artifactId: "12345678-1234-1234-1234-123456789abc",
                    targetEnvironment: "production"
                )
            }
        }
    }
}▼

Example using artifact URL and optional parameters

The following example uses the artifact URL and includes optional parameters:

pipeline {
    agent any

    stages {
        stage('Registering deployed artifact') {
            steps {
                echo 'Registering the deployment metadata'
                registerDeployedArtifactMetadata(
                    artifactUrl: "https://hub.docker.com/repository/docker/example",
                    targetEnvironment: "production",
                    labels: "latest",
                    allowNoMatchingComponent: true
                )
            }
        }
    }
}▼

Full pipeline example

The following example registers a build artifact and then registers its deployment. Running this pipeline creates a build artifact that is reported to CloudBees Unify, and then registers its deployment.

Example Jenkinsfile

pipeline {
    agent any

    stages {
        stage('Compile code') {
            steps {
                echo 'Compiling...'
            }
        }
        stage('Produce binary') {
            steps {
                echo 'Generating binary...'
            }
        }
        stage('Push binary') {
            steps {
                echo 'Pushing binary to ECR...'
            }
        }
        stage('Register build artifact') {
            steps {
                script {
                    env.ARTIFACT_ID = registerBuildArtifactMetadata(
                        name: "my-artifact",
                        version: "1.0.0",
                        url: "docker.io/example:latest",
                        type: "docker"
                    )
                }
            }
        }
        stage('Deploy artifact') {
            steps {
                echo "Deploying artifact ID: ${env.ARTIFACT_ID}"
            }
        }
        stage('Register deployed artifact') {
            steps {
                registerDeployedArtifactMetadata(
                    artifactId: env.ARTIFACT_ID,
                    targetEnvironment: "production",
                    labels: "latest"
                )
            }
        }
    }
}▼

After the run completes, the artifact information is displayed in the Run details Deployments tab in CloudBees Unify.

View deployed CI build artifacts

View deployed artifact data from your CI build in CloudBees Unify.

To view the deployed artifacts for a build:

Select the organization and component associated with the CI build.
Select Components Runs.
Select the build name to view the build details in Runs Run details.
Select Deployments to list only the deployed artifacts generated during that build.

For the full parameter specification and syntax, refer to Pipeline steps reference.

Register CI deployed artifacts

Configure your Multibranch Pipeline to register deployed artifacts

Usage examples

Basic example using artifact ID

Example using artifact URL and optional parameters

Full pipeline example

View deployed CI build artifacts

Related pages