Register and track artifacts

Register artifacts produced by your workflows to enable traceability across build and deployment, retrieve artifact details downstream, and manage artifact version labels. Refer to Understanding artifact management for an overview of the artifact lifecycle and why both build and deployment registration matter.

Register a build artifact

Use the cloudbees-io/register-build-artifact action to report to CloudBees Unify that an artifact version has been created from a workflow run. The action outputs a unique artifact ID that all downstream operations (deployment, promotion, labeling, and manifest inclusion) reference.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Do not use register-build-artifact for the same artifact version alongside any of the following actions, as the resulting run registers duplicate artifact entries: ecr-promote-image, s3-upload-object (if send-artifact-info: true), crane, helm-push, jfrog-artifactory-promote-image, jfrog-artifactory-upload-file (if send-artifact-info: true), or kaniko. These actions include built-in artifact registration.

Inputs and outputs

Table 1. Input details
Input name	Data type	Required?	Description
`commit`	String	Only required if a different repository/branch.^[1]	The commit ID from the source repository, used when registering the build artifact in CloudBees Unify. Default is `${{ cloudbees.scm.sha }}`.
`digest`	String	No, but recommended to track artifact versions across repositories in the artifact history.	The hash or checksum that uniquely identifies the artifact version.
`labels`	String	No	A comma-separated list of artifact labels. A maximum of 20 labels are allowed per artifact version, with a maximum of 20 characters per label.
`name`	String	Yes	The name of the artifact reported to CloudBees Unify.
`ref`	String	Only required if a different repository/branch.^[1]	The ref or branch of the source repository, used when registering the build artifact in CloudBees Unify. Default is `${{ cloudbees.scm.ref }}`.
`repository-url`	String	Only required if a different repository/branch.^[1]	The clone URL of the source repository, used when registering the build artifact in CloudBees Unify. Default is `${{ cloudbees.scm.repositoryUrl }}`.
`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 reported to CloudBees Unify.

^[1] By default, this action associates the artifact version with the code commit associated with the workflow run in the workflow’s repository/branch. If a different commit/repository/branch has been checked out for building the artifact, specify that commit ID instead. If you do not want to associate a commit with this artifact version, specify an empty commit.

Output: artifact-id (String): the unique identifier of the artifact reported to CloudBees Unify.

Usage examples

Basic example

jobs:
  register_build_artifact:
      uses: cloudbees-io/register-build-artifact@v2
      with:
        name: myApp
        url: docker.io/myapp/myimg:1.0.0
        version: 1.0.0▼

Use the artifact-id output in a downstream step

      - name: Checkout
        uses: cloudbees-io/checkout@v1
      - name: Register an artifact with {PRODUCT}
        id: register
        uses: cloudbees-io/register-build-artifact@v2
        with:
          name: myApp
          url: docker.io/myapp/myimg:1.0.0
          version: 1.0.0
      - name: Print output parameter artifact ID
        uses: docker://alpine:latest
        shell: sh
        run: |
           echo "artifact ID for myApp:${{ cloudbees.version }} is: ${{ steps.register.outputs.artifact-id }}"▼

Specify digest and labels

jobs:
  register_build_artifact:
      uses: https://github.com/cloudbees-io/register-build-artifact@v2
      with:
        name: myApp
        version: 1.0.0
        url: docker.io/myapp/myimg:1.0.0
        digest: sha256:1234567890abcdef1234567abcdef1234
        labels: label1, label2▼

Full workflow example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: My workflow

on:
  workflow_dispatch:

jobs:
  build:
    steps:
      - name: Checkout
        uses: cloudbees-io/checkout@v1
        id: checkout
      - name: Register an artifact with {PRODUCT}
        uses: cloudbees-io/register-build-artifact@v2
        id: register
        with:
          name: myApp
          url: docker.io/myapp/myimg:1.0.0
          version: 1.0.0
      - name: Print output parameter artifact ID
        uses: docker://alpine:latest
        shell: sh
        run: |
          echo "artifact ID for myApp:${{ cloudbees.version }} is: ${{ steps.register.outputs.artifact-id }}"▼

Register a deployed artifact

Use the cloudbees-io/register-deployed-artifact action to report to CloudBees Unify that an artifact has been deployed to an environment. This closes the traceability loop by linking a registered artifact version to a specific environment, keeping the environment inventory accurate.

Before using this action, you must first register the artifact you plan to deploy. Do one of the following in a prior workflow step: use register-build-artifact, use a publishing action that includes built-in registration (ecr-promote-image, s3-upload-object, crane, helm-push, jfrog-artifactory-promote-image, jfrog-artifactory-upload-file, or kaniko), or manually create an artifact version in the UI.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

This action (v2.0) is the most recent release. Previous releases are deprecated. Version 2.0 replaces multiple required inputs with a single artifact-id parameter.

Inputs

Table 2. Input details
Input name	Data type	Required?	Description
`artifact-id`	String	Yes	The unique identifier of the artifact ID output from CloudBees Unify.
`labels`	String	No	A comma-separated list of artifact labels. A maximum of 20 labels are allowed per artifact version, with a maximum of 20 characters per label.
`target-environment`	String	Required if no job-level `environment` is specified.	The environment where the deployment is located. The `target-environment` value overrides the job-level `environment` value.

Usage examples

Basic example

 jobs:
    register_artifact_version_to_my_env:
      environment: my_env
      steps:
        - name: Register deployed artifact
          uses: cloudbees-io/register-deployed-artifact@v2
          with:
            artifact-id: 1234abcd-56ef-ab78-9012-cdef78903456▼

Specify labels on deployment

 jobs:
    register_artifact_version_to_qa_env:
      environment: qa_env
      steps:
        - name: Register deployed artifact with labels
          uses: cloudbees-io/register-deployed-artifact@v2
          with:
            artifact-id: 1234abcd-56ef-ab78-9012-cdef78903456
            labels: label1,label2▼

Full workflow example with Kaniko

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Deployment workflow

on:
  workflow_dispatch:

jobs:
  build:
    outputs:
      artifact-id: ${{ fromJSON(steps.push-image.outputs.artifact-ids)[ format('index.docker.io/{0}/my-sample-go-app:{1}', vars.DOCKER_USERNAME, cloudbees.version) ] }}
    steps:
      - uses: docker://alpine/git:latest
        run: |
          git config --global --add safe.directory /cloudbees/workspace
      - name: checkout
        uses: cloudbees-io/checkout@v1
      - name: Build Go app
        uses: docker://golang:1.20
        kind: build
        run: |
          go build -v ./...
      - name: Set up Docker Hub registry
        uses: cloudbees-io/configure-oci-credentials@v1
        kind: deploy
        with:
          registry: index.docker.io
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: Push image to OCI registry
        id: push-image
        uses: cloudbees-io/kaniko@v1
        with:
          destination: index.docker.io/${{ vars.DOCKER_USERNAME }}/my-sample-go-app:${{cloudbees.version}}
  deploy:
    needs: build
    steps:
      - name: Register deployed artifact
        uses: cloudbees-io/register-deployed-artifact@v2
        with:
          artifact-id: ${{ needs.build.outputs.artifact-id }}
          target-environment: dev▼

Get artifact details

Use the cloudbees-io/get-artifact-details action to retrieve an artifact’s name, version, URL, and digest using its artifact ID. This is useful in downstream steps that need to reference artifact metadata without re-registering.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Inputs and outputs

Input: artifact-id (String, required): the unique identifier of the artifact ID output from CloudBees Unify.

Table 3. Output details
Output name	Data type	Description
`name`	String	The name of the artifact reported to CloudBees Unify.
`version`	String	The version of the artifact reported to CloudBees Unify.
`url`	String	The URL where the artifact version is located. For example, `docker.io/myapp/myimg:1.0.0`.
`digest`	String	The hash or checksum that uniquely identifies the artifact version.

Usage examples

Basic example

      - name: get-details
        uses: cloudbees-io/get-artifact-details@v1
        with:
          artifact-id: 1234abcd-56ef-ab78-9012-cdef78903456▼

Full workflow example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: My workflow

on:
  workflow_dispatch:

jobs:
  getArtifactDetailsAndPrint:
    steps:
      - name: Get artifact details
        id: getArtifactDetails
        uses: cloudbees-io/get-artifact-details@v1
        with:
          artifact-id: 1234abcd-56ef-ab78-9012-cdef78903456
      - name: Print artifact details
        id: printArtifactDetails
        uses: docker://golang:1.20.3-alpine3.17
        shell: sh
        run: |
          echo "Output from getArtifactDetails: "
          echo "name: ${{ steps.getArtifactDetails.outputs.name }}"
          echo "version: ${{ steps.getArtifactDetails.outputs.version }}"
          echo "url: ${{ steps.getArtifactDetails.outputs.url }}"
          echo "digest: ${{ steps.getArtifactDetails.outputs.digest }}"▼

Manage artifact version labels

Use the cloudbees-io/label-artifact-version action to add or remove labels on existing artifact versions. Labels are mutable tags on immutable artifact records. Use them to signal release readiness, approval status, or any other meaningful state.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Inputs

Table 4. Input details
Input name	Data type	Required?	Description
`artifact-id`	String	Yes	The unique identifier of an artifact version reported to CloudBees Unify.
`labels`	String	Yes	A comma-separated list of artifact labels. A maximum of 20 labels are allowed per artifact version, with a maximum of 20 characters per label.
`operation`	String	No	The labeling operation to perform. Supported values: `ADD` (default) to apply labels, or `REMOVE` to remove labels.

Usage examples

Add labels to an artifact version

The following example adds the labels For Production and Testing Passed to an existing artifact version:

jobs:
    add_labels_to_artifact_version:
        steps:
          - name: add_labels_to_artifact_version
            uses: cloudbees-io/label-artifact-version@v1
            with:
              artifact-id: 1234abcd-56ef-78ab-90cd-abcdab123456
              labels: For Production,Testing Passed▼

Remove labels from an artifact version

In the following example, an artifact version has been labelled with Label1, Label2, and Label3. Invoking this action removes Label2 and Label3, leaving the artifact labelled only with Label1:

        steps:
        - name: Unlabel an artifact version
          uses: cloudbees-io/label-artifact-version@v1
          with:
            artifact-id: 1234abcd-56ef-78ab-90cd-abcdab123456
            labels: Label2,Label3
            operation: REMOVE▼

Register and track artifacts

Register a build artifact

Inputs and outputs

Usage examples

Basic example

Use the artifact-id output in a downstream step

Specify digest and labels

Full workflow example

Register a deployed artifact

Inputs

Usage examples

Basic example

Specify labels on deployment

Full workflow example with Kaniko

Get artifact details

Inputs and outputs

Usage examples

Basic example

Full workflow example

Manage artifact version labels

Inputs

Usage examples

Add labels to an artifact version

Remove labels from an artifact version

Related pages