GitHub Action: Register a build artifact in the CloudBees Unify

Use this GitHub Action (GHA) for artifact traceability: Inform CloudBees Unify 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 CloudBees Unify, refer to the build artifacts documentation.

Prerequisites

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

Inputs

Table 1. Input details
Input name	Data type	Required?	Description
`cloudbees-url`	String	No	The CloudBees Unify URL. The default value is `https://api.cloudbees.io`.
`commit`	String	Only required if a different repository/branch.	The commit ID from the source repository, used when registering the build artifact in CloudBees Unify. The default is `${{ github.sha }}`.
`component-id`	String	No	The ID of the component associated with the artifact. If not provided, the default value is the component ID where the GHA workflow is located.
`digest`	String	No, but it is recommended to help track artifact versions across repositories.	The hash or checksum that uniquely identifies the artifact version. For more information, refer to Artifact deployment and publish history.
`label`	String	No	A comma-separated list of artifact labels.
`name`	String	Yes	The name of the artifact reported to CloudBees Unify.
`ref`	String	Only required if a different repository/branch.	The tag or branch of the source repository, used when registering the build artifact in CloudBees Unify. The default is `${{ github.ref }}`.
`repository-url`	String	Only required if a different repository/branch.	The clone URL of the source repository, used when registering the build artifact in CloudBees Unify. The default is `${{github.server_url }}/${{ github.repository }}`.
`type`	String	No	The type of artifact, such as Docker or Maven.
`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 CloudBees Unify for artifact traceability purposes.

Outputs

Table 2. Output details
Output name	Data type	Description
`cbp_artifact_id`	String	The identifier of the artifact sent to CloudBees Unify for artifact traceability purposes.

This version of the action uses GitHub OIDC authentication to securely communicate with CloudBees Unify. 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 CloudBees Unify, 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 CloudBees Unify. The artifact is shown to be published by the GHA workflow.

Figure 1. Artifact information in Artifacts