Register GHA build artifacts

Use the register-build-artifact and label-artifact-version GitHub Actions to register build artifact metadata from your GHA workflows to CloudBees Unify and manage artifact labels. For background on how artifact data flows through the platform, refer to Manage workflow artifacts.

Register a build artifact

Use the register-build-artifact action 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.

This action uses GitHub OIDC authentication to securely communicate with CloudBees Unify. Set permissions to id-token: write in your workflow.

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 recommended to help track artifact versions across repositories.	The hash or checksum that uniquely identifies the artifact version. For more information, refer to Manage workflow artifacts.
`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.

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▼

Manage artifact version labels

Use the label-artifact-version action to create, update, and remove labels on existing artifact versions in CloudBees Unify. For more information about organizing artifacts using labels, refer to Manage workflow artifacts.

Inputs

Table 3. Input details
Input name	Data type	Required?	Description
`artifact-id`	String	Yes	The identifier of the artifact version in CloudBees Unify.^[1]
`labels`	String	Yes	A comma-separated list of artifact labels.
`operation`	String	No	The labeling activity to perform. The following options are valid: `ADD`, to apply labels. `REMOVE`, to remove labels. The default is `ADD`.
`cloudbees-url`	String	No	The CloudBees Unify URL. The default value is `https://api.cloudbees.io`.

^[1] Obtain the multi-hexadecimal artifact ID from the output of running the Register a build artifact action in a GHA workflow.

Usage examples

The following basic example adds the labels For Production and Testing Passed to an existing artifact version:

        steps:
        - name: Revise artifact labeling
          uses: cloudbees-io-gha/label-artifact-version@v1
          with:
            artifact-id: "1234abcd-56ef-7812-90ab-1234abcd3456"
            labels: "For Production,Testing Passed"▼

In the following example, an artifact version has three labels, Label1, Label2, and Label3. Invoking the action removes the Label2 and Label3 labels, so that the artifact remains labeled only with Label1:

        steps:
        - name: Label an artifact
          uses: cloudbees-io-gha/label-artifact-version@v1
          with:
            artifact-id: "1234abcd-56ef-78ab-90cd-abc123123456"
            labels: "Label2,Label3"
            operation: REMOVE▼

The following example uses this action to register an artifact and then update its labels:

Example GHA workflow YAML file

name: Label artifacts

on:
    workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:

      - name: Register Build Artifact in Cloudbees Platform
        uses: cloudbees-io-gha/register-build-artifact@v3
        id: go-action
        with:
          name: "gha-artifact-test"
          version: 1.0.0
          url: "docker.io/example:latest"
          cloudbees-url: https://api.cloudbees.io
          digest: "sha256:1234567890abcdef1234abcdef1234567890134567890abcdef123456789012"
          label: "For testing"
          type: "docker"

      - name: Registered Build ArtifactId
        run: echo 'Registered Build ArtifactId ${{ steps.go-action.outputs.cbp_artifact_id }}'

      - name: Label Artifact -- remove
        uses: cloudbees-io-gha/label-artifact-version@v1
        with:
          artifact-id: ${{ steps.go-action.outputs.cbp_artifact_id }}
          labels: "For testing"
          operation: REMOVE

      - name: Label Artifact -- add
        uses: cloudbees-io-gha/label-artifact-version@v1
        with:
          artifact-id: ${{ steps.go-action.outputs.cbp_artifact_id }}
          labels: "For production"▼

After the run completes, the artifact label is updated from "For testing" to "For production" for the given artifact version, and the label is displayed in the Artifacts list in CloudBees Unify.

Register GHA build artifacts

Register a build artifact

Inputs

Outputs

Usage examples

Manage artifact version labels

Inputs

Usage examples

Related pages