Promote artifacts

Promote artifacts between registries and repositories as they progress through delivery stages using CloudBees actions for Amazon ECR, Crane, and JFrog Artifactory. Each promotion action registers the artifact at its new location, preserving the chain of custody in CloudBees Unify. Refer to Understanding artifact management for an explanation of the promotion pattern.

Amazon ECR and Crane promotion require AWS credentials or registry credentials to be configured before use. Refer to Configure AWS credentials and Configure container registry credentials.

Promote an image in Amazon ECR

Use the cloudbees-io/ecr-promote-image action to copy an image between Amazon ECR repositories. The action registers the promoted image as a new artifact in CloudBees Unify.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Automatic artifact data reporting

This action reports artifact-related data to the workflow run for artifact traceability purposes.

Do not include the Register and track artifacts action for the same artifact version, as the resulting run would register duplicate artifact entries to CloudBees Unify.

Inputs

Table 1. Input details
Input name	Data type	Required?	Description
`registry-url`	String	Yes	The Amazon ECR registry URL.
`source-repository-name`	String	Yes	The Amazon ECR source repository name.
`source-tag`	String	Yes	The Amazon ECR source image tag.
`target-repository-name`	String	Required only if `target-tag` is identical to `source-tag`.	The Amazon ECR target repository name.
`target-tag`	String	Required only if `target-repository-name` is identical to `source-repository-name`.	The Amazon ECR target image tag.
`artifact-name`	String	No	The name of the artifact, used when registering in CloudBees Unify. Defaults to the target repository name.
`component-id`	String	No	The ID of the component associated with the artifact. Defaults to the component of the current workflow run (`${{ cloudbees.component.id }}`).

Output: artifact-id (String): the unique identifier of the artifact reported to CloudBees Unify.

Usage examples

Basic example

      - name: Promote an image in ECR
        uses: cloudbees-io/ecr-promote-image@v1
        with:
           registry-url: ${{ vars.EC_REGISTRY_URL }}
           source-repository-name: my-ecr-repo-name
           source-tag: 6▼

Specify target repository when source and target tags are identical

      - name: Promote an image in ECR
        uses: cloudbees-io/ecr-promote-image@v1
        with:
           registry-url: ${{ vars.REGISTRY_URL }}
           source-repository-name: my-source-repo-name
           source-tag: 2
           target-repository-name: my-target-repo-name
           target-tag: 2▼

Full workflow example

name: ecr-promote-image
kind: workflow
apiVersion: automation.cloudbees.io/v1alpha1

on:
  push:
    branches:
      - main

jobs:
  ec2-promote-image-job:
    steps:
      - name: Configure AWS credentials
        uses: cloudbees-io/configure-aws-credentials@v1
        with:
          aws-region: us-west-1
          aws-access-key-id: ${{ secrets.MY_AWS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.MY_AWS_ACCESS_KEY }}
      - name: ECR promote image
        id: ecr-promote
        uses: cloudbees-io/ecr-promote-image@v1
        with:
           registry-url: 123456789012.dkr.ecr.us-west-1.amazonaws.com
           source-repository-name: my-repo-name
           source-tag: ABC-1234-567a890b1234567890bcde1234567890abcde123
           target-tag: my-target-tag
      - name: Print output parameter artifact ID from ECR promote action
        uses: docker://alpine:latest
        shell: sh
        run: |
          echo "artifact ID for the artifact my-repo-name:my-target-tag is: ${{ steps.ecr-promote.outputs.artifact-id }}"▼

Copy a container image with Crane

Use the cloudbees-io/crane action to copy a container image from any source registry to any destination registry, independent of cloud provider. The action registers the destination image as a new artifact in CloudBees Unify.

Before invoking this action, you must have a Docker config file at ${HOME}/.docker/config.json to authenticate with the Docker registry. Use cloudbees-io/configure-oci-credentials for OCI registries or cloudbees-io/configure-ecr-credentials for ECR registries to generate this file. If your source and destination registries are different, authenticate to both registries before invoking Crane.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Automatic artifact data reporting

This action reports artifact-related data to the workflow run for artifact traceability purposes.

Do not include the Register and track artifacts action for the same artifact version, as the resulting run would register duplicate artifact entries to CloudBees Unify.

Inputs

Table 2. Input details
Input name	Data type	Required?	Description
`src`	String	Yes	The source image to copy.
`destination`	String	Yes	The destination image.
`platform`	String	No	Specifies the platform in the format `os/arch[/variant][:osversion]`.
`registry-configuration`	String	No	CloudBees registry configuration file containing the registries to use for loading images. Defaults to `${{ cloudbees.registries }}`.
`skip-image-validation`	String	No	When `true`, source and destination image validation is skipped. Default is `true`.
`artifact-name`	String	No	The name of the artifact, used when registering in CloudBees Unify. Defaults to the destination image name without registry and tag parts.
`component-id`	String	No	The ID of the component associated with the artifact. Defaults to the component of the current workflow run (`${{ cloudbees.component.id }}`).

Outputs: artifact-id (String), digest (String: image digest of the destination image), image (String: image reference of the destination image including digest).

Usage examples

Basic example

      - name: Copy remote image with Crane
        id: copy-image
        uses: cloudbees-io/crane@v1
        with:
          src: my-source-registry/source-image-name:source-tag-name
          destination: my-destination-registry/destination-image-name:destination-tag-name▼

Specify platform and enable image validation

      - name: Copy remote image with Crane
        id: copy-image
        uses: cloudbees-io/crane@v1
        with:
          src: my-source-registry/source-image:source-tag
          destination: my-destination-registry/destination-image:destination-tag
          platform: linux/arm/v7
          skip-image-validation: false▼

Use the action outputs in a downstream step

      - name: Run Crane action
        id: promotecharts
        uses: cloudbees-io/crane@v1
        with:
          src: ghcr.io/nginxinc/charts/nginx-ingress:1.0.2
          destination: ${{ vars.my_chart_registry }}/nginx-ingress:1.0.2
      - name: Crane output
        uses: docker://gcr.io/go-containerregistry/crane:debug
        run: |
          echo "artifact ID for ${{ vars.my_chart_registry }}/nginx-ingress:1.0.2: ${{ steps.promotecharts.outputs.artifact-id }}"
          echo "digest for ${{ vars.my_chart_registry }}/nginx-ingress:1.0.2: ${{ steps.promotecharts.outputs.digest }}"
          echo "image for ${{ vars.my_chart_registry }}/nginx-ingress:1.0.2: ${{ steps.promotecharts.outputs.image }}"▼

Full workflow example

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Action test

on:
  push:
    branches:
    - '**'

permissions:
  scm-token-own: read
  scm-token-org: read
  id-token: write

jobs:
  docker-build:
    steps:
    - name: Check out source code
      uses: cloudbees-io/checkout@v1
      with:
        repository: my-name/my-repo-name
    - name: Configure container registry credentials
      uses: cloudbees-io/configure-oci-credentials@v1
      with:
        registry: docker.io
        username: ${{ secrets.DOCKER_USERNAME }}
        password: ${{ secrets.DOCKER_PASSWORD }}
    - name: Log in to AWS
      uses: cloudbees-io/configure-aws-credentials@v1
      with:
        aws-region: us-east-1
        role-to-assume: ${{ vars.MY_ROLE }}
        role-duration-seconds: 3600
    - name: Run Crane action
      id: run-crane
      uses: cloudbees-io/crane@v1
      with:
        src: ubuntu:latest
        destination: ${{ vars.my_image_registry }}/ubuntu:test
        platform: linux/amd64
        skip-image-validation: false
    - name: Test Crane action output
      uses: docker://gcr.io/go-containerregistry/crane:debug
      run: |
        SRC_DIGEST=$(crane digest ubuntu:latest --platform linux/amd64)
        DEST_DIGEST=$(crane digest ${{ vars.my_image_registry }}/ubuntu:test --platform linux/amd64)
        [ "$DEST_DIGEST" = '${{ steps.run-crane.outputs.digest }}' ]
        [ "$SRC_DIGEST" = "$DEST_DIGEST" ]▼

Promote an image in JFrog Artifactory

Use the cloudbees-io/jfrog-artifactory-promote-image action to move or copy a Docker image between JFrog Artifactory repositories. The action registers the promoted image as a new artifact in CloudBees Unify.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Automatic artifact data reporting

This action reports artifact-related data to the workflow run for artifact traceability purposes.

Do not include the Register and track artifacts action for the same artifact version, as the resulting run would register duplicate artifact entries to CloudBees Unify.

Inputs

Table 3. Input details
Input name	Data type	Required?	Description
`source-image-name`	String	Yes	The JFrog Artifactory source image name.
`source-repository-name`	String	Yes	The JFrog Artifactory source repository name.
`source-tag`	String	Yes	The JFrog Artifactory source tag.
`url`	String	Yes	The JFrog Artifactory server URL.
`token`	String	Required only if `username` and `password` are not specified.	The JFrog Artifactory token.
`username`	String	Required only if `token` is not specified.	The JFrog Artifactory username.
`password`	String	Required only if `token` is not specified.	The JFrog Artifactory password.
`target-image-name`	String	Required only if `target-repository-name` and `target-tag` are not specified.	The JFrog Artifactory target image name.
`target-repository-name`	String	Required only if `target-image-name` and `target-tag` are not specified.	The JFrog Artifactory target repository name.
`target-tag`	String	Required only if `target-repository-name` and `target-image-name` are not specified.	The JFrog Artifactory target tag.
`copy`	String	No	Specifies whether to move or copy the image. Default (`''`) moves the image; `true` copies it.

Output: artifact-id (String): the unique identifier of the artifact reported to CloudBees Unify.

Usage examples

Move an image to a target repository

      - name: Promote an image
        uses: cloudbees-io/jfrog-artifactory-promote-image@v1
        with:
          source-image-name: source-image
          source-repository-name: local-test
          source-tag: 1
          url: ${{ vars.JFROG_URL }}
          username: ${{ secrets.JFROG_USERNAME }}
          password: ${{ secrets.JFROG_PASSWORD }}
          target-repository-name: test▼

Copy an image to a new destination

      - name: Copy an image
        uses: cloudbees-io/jfrog-artifactory-promote-image@v1
        with:
          source-image-name: my-source-image
          source-repository-name: my-repo
          source-tag: 1
          url: ${{ vars.JFROG_URL }}
          token: ${{ secrets.JFROG_TOKEN }}
          target-image-name: target-image
          target-repository-name: my-target-repo
          target-tag: 12
          copy: copy▼

Full workflow example

name: jfrog-artifactory-promote-image
kind: workflow
apiVersion: automation.cloudbees.io/v1alpha1

on:
  push:
    branches:
      - main

jobs:
  promote-image-job:
    steps:
      - name: Check out source code
        uses: cloudbees-io/checkout@v1
      - name: JFrog Artifactory promote image
        id: promote-image
        uses: cloudbees-io/jfrog-artifactory-promote-image@v1
        with:
          source-image-name: my-docker-image
          source-repository-name: jfrog-repo-1
          source-tag: '1.0.0'
          url: ${{ vars.JFROG_URL }}
          username: ${{ vars.JFROG_USERNAME }}
          password: ${{ secrets.JFROG_PASSWORD }}
          target-repository-name: jfrog-repo-2
          copy: 'true'
      - name: Print output parameter artifact ID from JFrog promote action
        uses: docker://alpine:latest
        shell: sh
        run: |
          echo "artifact ID for the artifact my-docker-image:1.0.0 at jfrog-repo-2 is: ${{ steps.promote-image.outputs.artifact-id }}"▼

Promote artifacts

Promote an image in Amazon ECR

Automatic artifact data reporting

Inputs

Usage examples

Basic example

Specify target repository when source and target tags are identical

Full workflow example

Copy a container image with Crane

Automatic artifact data reporting

Inputs

Usage examples

Basic example

Specify platform and enable image validation

Use the action outputs in a downstream step

Full workflow example

Promote an image in JFrog Artifactory

Automatic artifact data reporting

Inputs

Usage examples

Move an image to a target repository

Copy an image to a new destination

Full workflow example

Related pages