GitHub Action: Manage artifact labels in the CloudBees platform

Use this GitHub Action (GHA) to create, update, and remove labels on existing artifacts in the CloudBees platform. To learn more about organizing your artifacts using labels, refer to Artifact labels.

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
`artifact-id`	String	Yes	The identifier of the artifact in the CloudBees platform.^[1]
`labels`	String	Yes	A comma-separated list of artifact labels.
`operation`	String	No	The labeling activity to be performed. The following options are valid: `ADD`, to apply label(s). `REMOVE`, to remove label(s). The default is `ADD`.
`cloudbees-url`	String	No	The CloudBees platform URL. The default value is `https://api.cloudbees.io`.

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

Usage examples

Basic example

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

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

Removing labels

In the following example, an artifact 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-78gh-90ij-klmnop123456"
            labels: "Label2,Label3"
            operation: REMOVE▼

Updating labels

The following GHA workflow example uses this action to register an artifact and then update its labels in the CloudBees platform.

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:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
          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 has completed, 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 tab in the platform.