CloudBees action: Register a build artifact

Use this action to report to CloudBees Unify that an artifact version has been created from a workflow run. Register a build artifact to enable traceability, including if a branch and/or repository is checked out that is different from the workflow repository branch. A unique artifact ID is output from using this action.

Important

This action version (v2.0) is the most recent release of the action. Previous releases are deprecated. Version 2.0 removes commit_url.

Note

Do not include the register-build-artifact action for the same artifact version with any of the following actions, as the resulting run would register duplicate artifact entries to CloudBees Unify. Promote an image in Amazon ECR Store an object on Amazon S3 (if send-artifact-info: true) Copy Docker images with Crane Push a Helm chart Promote an image from JFrog Artifactory Upload a file to JFrog Artifactory (if send-artifact-info: true) Build and publish Docker images with Kaniko

Inputs

Table 1. Input details

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 reported to CloudBees Unify.
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 }}.
ref	String	Only required if a different repository/branch.[1]	The tag 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 }}.
digest	String	No, but recommended in order to track artifact versions across repositories in the history.	The hash or checksum that uniquely identifies the artifact version.
labels	String	No	A comma-separated list of artifact labels. NOTE: A maximum of 20 labels are allowed per artifact version, with a maximum of 20 characters per label.
component-id	String	No	The ID of the component associated with the artifact. If not provided, the artifact is registered with the component of the current workflow run. Default is ${{ cloudbees.component.id }}
type	String	No	The type of artifact, e.g., docker, helm, maven, etc. This field is for display purposes only.

^[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.

Outputs

Table 2. Output details

Output name	Data type	Description
artifact-id	String	The unique identifier of the artifact reported to CloudBees Unify.

Usage examples

Basic example

The following is a basic example of using the action:

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",
        type: "docker"

Using the action output

The following example accesses the artifact-id value in a downstream step using the outputs context.

      - name: Checkout
        uses: cloudbees-io/checkout@v1
      - name: Register an artifact with the CloudBees Unify
        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 }}"

Using optional inputs

The following example specifies the artifact 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

The following workflow example uses the action to register a build artifact to CloudBees Unify. Then it prints the artifact ID output parameter.

Example CloudBees Unify workflow YAML file

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 the CloudBees Unify
        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 }}"

License

This code is made available under the MIT license.

References

• Learn more about using actions in CloudBees workflows.

• Learn about CloudBees Unify.