GitHub Action: Register a build artifact in the CloudBees platform

2 minute read
On this page

Use this GitHub Action (GHA) for artifact traceability: Inform the CloudBees platform that an artifact version has been created, and report any build artifact data generated by a GHA workflow run.

This action is available on the GitHub marketplace.

To learn more about working with artifacts in the platform, refer to the build artifacts documentation.

Prerequisites

Set up the CloudBees platform and GHA to work together, providing key features of the platform to GHA workflows. Refer to Getting started for more information.

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 to send to the CloudBees platform for artifact traceability purposes.

cloudbees-url

String

No

The CloudBees platform URL. The default value is https://api.cloudbees.io.

commit

String

No

The commit ID from the source repository.

digest

String

No, but it is recommended to help track artifact versions across repositories. For more information, refer to Artifact deployment and publish history.

The hash or checksum that uniquely identifies the artifact version.

label

String

No

A comma-separated list of artifact labels.

ref

String

No

The ref or branch of the artifact repository.

repository-url

String

No

The clone URL of the source code repository.

type

String

No

The type of artifact, such as Docker or Maven.

Outputs

Table 2. Output details
Output name Data type Description

cbp_artifact_id

String

The identifier of the artifact sent to the CloudBees platform for artifact traceability purposes.

This version of the action uses GitHub OIDC authentication to securely communicate with the CloudBees platform. Be sure to set permissions to id-token: write in your workflow.

Usage examples

The following is a basic example of using the action:

permissions: id-token: write contents: read steps: - name: register-artifact-step uses: cloudbees-io-gha/register-build-artifact@v3 with: name: my-artifact url: https://my-artifact-url.com version: 1.0.0

The following example specifies optional inputs:

permissions: id-token: write contents: read steps: - name: register-artifact-step-with-options uses: cloudbees-io-gha/register-build-artifact@v3 with: name: my-Docker-artifact url: https://hub.docker.com/repository/docker/example version: 1.0.0 commit: 1234abcd-ab34-123cd-56ef-12345678abcd digest: sha256:abcdef1234567890 label: staging,prod repository-url: http://github.com/example/repo ref: main type: Docker

Full workflow and run example

The following GHA workflow example uses version v3 of this action. Running this workflow creates an artifact that is reported to the platform, and the artifact is shown as published by the GHA workflow.

Example GHA workflow YAML file
name: GHA Workflow on: workflow_dispatch: jobs: build: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - name: Compile Code run: echo "Compiling..." - name: Produce Binary run: sleep 10 - name: Push binary run: echo "Pushing Binary to ECR..." - name: Register Build Artifacts in Cloudbees Platform uses: cloudbees-io-gha/register-build-artifact@v3 id: go-action with: name: "gha-artifact-step" version: 1.0.0 url: "docker.io/example:latest" digest: sha256:1234567890abcdef123456123456abcdef789078907890abcdefabcdef123456 label: For testing type: docker - name: Registered Build ArtifactId run: echo 'Registered Build ArtifactId ${{ steps.go-action.outputs.cbp_artifact_id }}' deploy: runs-on: ubuntu-latest needs: [build] # Depends on 'build' job steps: - name: Checkout to Prepare Manifest uses: actions/checkout@v3 - name: Trigger Deployment run: echo "Invoking CBP Deploy Workflow..."

After the run has completed, the artifact information is displayed in both Components  Artifacts and Run details  Build artifacts in the CloudBees platform. The artifact is shown to be published by the GHA workflow.

Artifact reported to platform
Figure 1. Artifact information in Components  Artifacts