CloudBees action: Register a build artifact

Use this action to report to CloudBees platform 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.

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 platform.

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

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

Inputs

Table 1. Input details
Input name	Data type	Required?	Description
`name`	String	Yes	The name of the artifact reported to CloudBees platform.
`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 platform.
`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 platform. Default is `${{ cloudbees.scm.sha }}`.
`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 platform. 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 platform. 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.

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

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▼

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 platform
        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 platform. Then it prints the artifact ID output parameter.

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 platform
        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 }}"▼