GitHub Action: Register a build artifact in the CloudBees platform

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.

There are two versions of this action:

Version v2 of this action is a Preview feature and is not yet fully supported by CloudBees.
Version v1 of this action is fully supported by CloudBees for all users.

Version v1 associates the given artifact to the component, whereas version v2 associates the given artifact to both the component and the workflow run.

Version v2

Use version v2 with an upcoming new feature: direct viewing of GHA workflows and runs. This new feature also allows GHA build artifact traceability in the CloudBees platform.

Version v2 of this GHA is a Preview feature:

A Preview feature:

Has not undergone end-to-end testing with CloudBees products.
Is provided without service-level agreements (SLA), and therefore does not include CloudBees' commitment to functionality or performance.
May impact other stable areas of the product when used.
May have limited documentation.
May not be feature-complete during the Preview period.
May graduate from Preview to a supported feature or be removed from the product.
May introduce breaking changes that prevent upgrades due to incompatibility with future development.

Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

V2 inputs

Table 1. Input details
Input name	Data type	Required?	Description
`cloudbees-pat`	String	Yes	The CloudBees platform personal access token.
`name`	String	Yes	The name of the artifact to send to the CloudBees platform for artifact traceability purposes.
`version`	String	Yes	The version of the artifact to send to the CloudBees platform for artifact traceability purposes.
`url`	String	Yes	The URL where the artifact version can be pulled for deployment.
`cloudbees-url`	String	No	The CloudBees platform URL. The default value is `"https://api.cloudbees.io"`.
`digest`	String	No	The artifact digest that uniquely identifies the artifact.
`type`	String	No	The type of artifact, such as Docker or Maven.

V2 usage examples

The following is a basic example of using the v2 action:

steps:
      - name: register-artifact-step
        uses: cloudbees-gha-cbp/register-build-artifact@v2
        with:
          cloudbees-pat: ${{ secrets.CloudBees-platform-PAT }}
          name: my-artifact
          version: 1.0.0
          url: "https://my-artifact-url.com"▼

The following example specifies the artifact digest:

steps:
      - name: register-artifact-step-digest
        uses: cloudbees-gha-cbp/register-build-artifact@v2
        with:
          cloudbees-url: "https://api.cloudbees.io"
          cloudbees-pat: ${{ secrets.CloudBees-platform-PAT }}
          name: my-Docker-artifact
          version: 1.0.0
          url: "https://hub.docker.com/repository/docker/example"
          digest: "sha256:abcdef1234567890"
          type: "Docker"▼

Full workflow and run example

The following GHA workflow example uses version v2 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
    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-gha-cbp/register-build-artifact@v2
        id: go-action
        with:
          name: "gha-artifact-test"
          version: 1.0.0
          url: "docker.io/example:latest"
          digest: "sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
          type: "docker"
          cloudbees-url: "https://api.cloudbees.io"
          cloudbees-pat: ${{ secrets.CBP_PAT }}
  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.

Figure 1. Artifact information in Artifacts

Version v1

Learn more about Using GitHub Actions with the CloudBees platform.

Version v1 of this action is available for general use and has been fully tested by CloudBees. Version v1 associates the given artifact to the component only, not the workflow run.

V1 inputs

Table 2. Input details
Input name	Data type	Required?	Description
`cloudbees-url`	String	Yes	The CloudBees platform URL. Typically, this value is `"https://api.cloudbees.io"`.
`cloudbees-pat`	String	Yes	The CloudBees platform personal access token.
`component-id`	String	Yes	The CloudBees platform component identifier. This multi-hexadecimal UUID can be found by: Navigating to a component on the CloudBees platform. Locating the ID value in the component URL after `componentId=`.
`name`	String	Yes	The name of the artifact to send to the CloudBees platform for artifact traceability purposes.
`version`	String	Yes	The version of the artifact to send to the CloudBees platform for artifact traceability purposes.
`url`	String	Yes	The URL where the artifact version can be pulled for deployment.
`digest`	String	No	The artifact digest that uniquely identifies the artifact.

V1 usage example

In your YAML file, add:

steps:
      - name: <step-name>
        uses: cloudbees-gha-cbp/register-build-artifact@v1
        with:
          component-id: <component-id>
          name: <artifact-name>
          version: <artifact-version>
          url: <artifact-repo-url>
          digest: <artifact-digest>
          cloudbees-url: <cloudbees-url>
          cloudbees-pat: ${{ <secrets.CloudBees-platform-PAT> }}▼