CloudBees action: Register a build artifact

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

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 the 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 the CloudBees platform.
`commit`	String	Only required if a different repository/branch.^[1]	The commit ID from the source repository.
`commit-url`	String	Only required if a different repository/branch.^[1]	The commit URL from the source repository.
`ref`	String	Only required if a different repository/branch.^[1]	The ref or branch of the artifact repository.
`repository-url`	String	Only required if a different repository/branch.^[1]	The artifact repository URL.
`digest`	String	No, but it is recommended to help track artifact versions across repositories. Refer to history for more information.	The hash or checksum that uniquely identifies the artifact version.
`labels`	String	No	A comma-separated list of artifact labels.

^[1] By default, the CloudBees platform 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.

Outputs

Table 2. Output details
Output name	Data type	Description
`artifact-id`	String	The unique identifier of the artifact reported to the 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@v1
      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@v1
        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@v1
      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 the platform. Then it prints the artifact ID output parameter.

Example platform 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 platform
        uses: cloudbees-io/register-build-artifact@v1
        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 }}"▼