CloudBees action: Build and publish Docker images with Kaniko

Use the Kaniko action to build images based upon a Dockerfile, then publish the image to a Docker registry. Kaniko builds images inside a container or Kubernetes cluster. This action also publishes the image and tag names to the platform for artifact traceability purposes. View build artifact information in Build artifacts of Run details and in Artifacts.

Automatic artifact data reporting

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

Do not include the register-build-artifact action for the same artifact version, as the resulting run would register duplicate artifact entries to CloudBees platform.

Prerequisites

To authenticate with the Docker registry, you must have a Docker config file in the ${HOME}/.docker/config.json path.

Use the OCI credentials configuration action to generate a Docker config file, as in the following example.

In your YAML file, add:

      - id: dockerconfig
        name: Configure container registry credentials
        uses: cloudbees-io/configure-oci-credentials@v1
        with:
          registry: ${{ vars.DOCKER_REGISTRY }}
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

The generated Docker config file is formatted in JSON.

Inputs

Table 1. Input details

Input name	Data type	Required?	Description
destination	String	Yes	The locations of the target images to be published. Formatted as a comma-separated list for passing multiple images.
build-args	String	No	The build arguments to be passed to the Kaniko build. Formatted as a comma-separated list for passing multiple build arguments.
context	String	No	The path to the build context. Default is ${{ cloudbees.workspace }}.
dockerfile	String	No	The path to the Dockerfile. Default is Dockerfile.
labels	String	No	The label metadata added to the final image. Formatted as a comma-separated list for passing multiple labels.
registry-mirrors	String	No	Registry mirrors to use for loading images. Formatted as a comma-separated list for passing multiple registries.
skip-default-registry-fallback	Boolean	No	If set to true, fails build if registry-mirrors cannot pull the image. If registry-mirrors is empty, this flag is ignored. Default is false.
target	String	No	Specify a target stage to build when using a multi-stage Dockerfile.
tar-path	String	No	Full path location where the image is to be saved, including the filename. To use this option, the image file must be in the TAR format.
verbosity	String	No	The verbosity of logging when running the Kaniko build. Accepted inputs are: panic, fatal, error, warn, info, debug, trace. Default is info.
commit	String	Only required if a different repository/branch.[1]	The commit ID from the source repository, used when registering the build artifact in CloudBees platform. Default is ${{ cloudbees.scm.sha }}.
repository-url	String	Only required if a different repository/branch.[1]	The clone URL of the source repository, used when registering the build artifact in CloudBees platform. Default is ${{ cloudbees.scm.repositoryUrl }}.
ref	String	Only required if a different repository/branch.[1]	The tag or branch of the source repository, used when registering the build artifact in CloudBees platform. Default is ${{ cloudbees.scm.ref }}.
artifact-name	String	No	The name of the build artifact to register. If not specified, the artifact name defaults to the image name portion of the first destination input value.
component-id	String	No	The ID of the component associated with the artifact. If not provided, the artifact is registered with the component of the current workflow run. Default is ${{cloudbees.component.id}}.

^[1] By default, this action associates the artifact version with the code commit associated with the workflow run in the workflow’s repository/branch. If a different commit/repository/branch has been checked out for building the artifact, specify that commit ID instead. If you do not want to associate a commit with this artifact version, specify an empty commit.

Output

Table 2. Output details

Output name	Data type	Description
artifact-ids	JSON string	The unique identifiers for each of the published image locations (destination) reported to CloudBees platform, in JSON format.
digest	String	The image digest.
image	String	Image reference of the first specified destination and the image digest, in a format not part of the OCI standard but supported by most container tools. Tools loading such an image reference ignore the tag, which serves as a hint for humans, but perform the lookup based on the image repository and digest only. Use this image reference format to guarantee that the same image is used even if the tag has been overwritten, and to prevent stale image caches on different nodes.
tag	String	The tag of the first pushed image.
tag-digest	String	The tag of the first specified destination and the image digest, in a format not part of the OCI standard but supported by most container tools. Tools loading such an image reference ignore the tag, which serves as a hint for humans, but perform the lookup based on the image repository and digest only. Use this format to guarantee that the same image is used even if the tag has been overwritten, and to prevent stale image caches on different nodes.

Usage examples

Basic example

The following is a basic usage example for this action:

      - name: Build a container image with Kaniko
        uses: cloudbees-io/kaniko@v1
        with:
          destination: path/to/registry/host/my-image:1.0.1,path/to/registry/host/my-image:latest

Using optional inputs

The following example specifies optional inputs:

      - name: Kaniko build with optional inputs
        uses: cloudbees-io/kaniko@v1
        with:
          destination: path/to/registry/host/my-image:1.0.1,path/to/registry/host/my-image:latest
          build-args: BUILDKIT_CONTEXT_KEEP_GIT_DIR=1,BUILDKIT_INLINE_CACHE=1
          context: .
          dockerfile: path/to/Dockerfile
          labels: maintainer=John Smith,version=1.0.1
          tar-path: path/to/image.tar
          verbosity: warn

Using the action output

Access the artifact-ids values in downstream steps using the outputs context.

The following is the JSON format for the artifact-ids ouput, where <destination> is the specified destination input parameter value, and <artifact-version-id> is the unique identifier of the artifact version.

{
  "<destination>": "<artifact-version-id>"
}

The following is an example of an artifact-ids JSON for two artifact IDs:

{
  "index.docker.io/example/my-docker:1.0.87": "1234abcd-56ef-gh78-9012-ijklmnop3456",
  "index.docker.io/example/my-docker:1.0.87-dev": "ab34cd12-78gh-56ef-ij78-3456mnopkl90"
}

Use the artifact-ids output as follows, where <action_step_ID> is the action step ID, and <destination_URL> is the destination URL:

• ${{ steps.<action_step_ID>.outputs.artifact-ids }} for a JSON string of all outputted artifact ID values.

• ${{ fromJSON(steps.<action_step_ID>.outputs.artifact-ids).<destination_URL> }} for a single artifact ID value.

Full workflow example

The following workflow example:

• Checks out source code from a repository.

• Configures Docker credentials.

• Builds and publishes a container image with Kaniko.

• Prints the artifact IDs for dynamically created destinations.

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: workflow
on:
  push:
    branches:
      - "*"

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

jobs:
  build:
    steps:
      - name: Check out
        uses: cloudbees-io/checkout@v1
        with:
          repository: my-name/my-repo-name
      - name: Configure container registry credentials
        id: dockerconfig
        uses: cloudbees-io/configure-oci-credentials@v1
        with:
          registry: ${{ vars.DOCKER_REGISTRY }}
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: Build with Kaniko
        id: kaniko-build
        uses: cloudbees-io/kaniko@v1
        kind: build
        with:
          destination: ${{ vars.DOCKER_REGISTRY }}/my-image:${{ cloudbees.version }},${{ vars.DOCKER_REGISTRY }}/my-image-test:${{ cloudbees.version }}
          dockerfile: my-dockerhub/docker/config.json
      - name: Print output parameter artifact IDs from Kaniko action
        id: echo-artifact-ids
        uses: docker://alpine:latest
        shell: sh
        env:
          DESTINATION1:  "${{ vars.DOCKER_REGISTRY }}/my-image:${{ cloudbees.version }}"
          DESTINATION2:  "${{ vars.DOCKER_REGISTRY }}/my-image-test:${{ cloudbees.version }}"
        run: |
          echo "artifact ID for my-image:${{ cloudbees.version }}: '${{ env.DESTINATION1 }}': ${{ fromJSON(steps.kaniko-build.outputs.artifact-ids)[env.DESTINATION1] }}"
          echo "artifact ID for my-image-test:${{ cloudbees.version }}: '${{ env.DESTINATION2 }}': ${{ fromJSON(steps.kaniko-build.outputs.artifact-ids)[env.DESTINATION2] }}"

License

This code is made available under the MIT license.

References

• Learn more about using actions in CloudBees workflows.

• Learn about CloudBees platform.