Build and publish container images

Build a container image from a Dockerfile and publish it to a Docker registry using the Kaniko action. Kaniko builds images inside a container or Kubernetes cluster and reports the image and tag names to the workflow run for artifact traceability. View build artifact information in the workflow Runs Run details Build artifacts and artifacts in Components Artifacts.

To authenticate with the Docker registry, you must have a Docker config file at ${HOME}/.docker/config.json. Use the configure-oci-credentials action to generate the file before running the Kaniko step. Refer to Configure container registry credentials for details.

      - 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 }}▼

Build and publish an image

The following is a basic example that builds and publishes an image to two destinations:

      - 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▼

Use optional inputs

The following example specifies optional inputs to control the build context, Dockerfile path, labels, and verbosity:

      - 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▼

Access build outputs

The action returns an artifact-ids output containing the unique identifiers for each published image destination, in JSON format.

The format for a single destination is:

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

The following is an example with 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"
}▼

Access the output in downstream steps as follows, where <action_step_ID> is the step ID and <destination_URL> is the destination URL:

${{ steps.<action_step_ID>.outputs.artifact-ids }}: a JSON string of all artifact ID values.
${{ fromJSON(steps.<action_step_ID>.outputs.artifact-ids).<destination_URL> }}: a single artifact ID value.

Full workflow example

The following workflow checks out source code, configures Docker credentials, builds and publishes a container image with Kaniko, and prints the artifact IDs:

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] }}"▼

Inputs

Table 1. Input details
Input name	Data type	Required?	Description
`artifact-name`	String	No	The name of the build artifact to register. If not specified, defaults to the image name portion of the first `destination` input value.
`build-args`	String	No	The build arguments to pass to the Kaniko build. Formatted as a comma-separated list for multiple build arguments.
`commit`	String	No	The commit ID from the source repository, used when registering the build artifact in CloudBees Unify. Default is `${{ cloudbees.scm.sha }}`.
`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}}`.
`context`	String	No	The path to the build context. Default is `${{ cloudbees.workspace }}`.
`destination`	String	Yes	The locations of the target images to be published. Formatted as a comma-separated list for multiple images.
`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 multiple labels.
`ref`	String	No	The ref or branch of the source repository, used when registering the build artifact in CloudBees Unify. Default is `${{ cloudbees.scm.ref }}`.
`registry-mirrors`	String	No	Registry mirrors to use for loading images. Formatted as a comma-separated list for multiple registries.
`repository-url`	String	No	The clone URL of the source repository, used when registering the build artifact in CloudBees Unify. Default is `${{ cloudbees.scm.repositoryUrl }}`.
`skip-default-registry-fallback`	Boolean	No	If set to `true`, fails the 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. The image file must be in TAR format.
`verbosity`	String	No	The verbosity of logging when running the Kaniko build. Accepted values are `panic`, `fatal`, `error`, `warn`, `info`, `debug`, and `trace`. Default is `info`.

Outputs

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 Unify, 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 and 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.
`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 and 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.