Docker Build & Push Action

Builds a Docker image and pushes it to the private registry of your choosing.

Supported Docker registries

• Docker Hub
• Google Container Registry (GCR)
• AWS Elastic Container Registry (ECR)
• GitHub Docker Registry

Features

• Auto-tagging with GitOps
• BuildKit support
• Multi-platform builds

Breaking changes

If you're experiencing issues, be sure you are using the latest stable release (currently v6).

v6

• Multi-platform builds now supported
• SSH agent forwarding

v5

• AWS ECR get-login command became deprecated, migrated to get-login-password command
• Support for multiple tags added
• BuildKit support added

Basic usage

• Ensure you run the checkout action before using this action
• Add the following to a workflow .yml file in the /.github directory of your repo

steps:
  - uses: actions/checkout@v3
    name: Check out code

  - uses: mr-smithers-excellent/docker-build-push@v6
    name: Build & push Docker image
    with:
      image: repo/image
      tags: v1, latest
      registry: registry-url.io
      dockerfile: Dockerfile.ci
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}

Inputs

Outputs

Storing secrets

It is strongly recommended that you store all Docker credentials as GitHub encrypted secrets. Secrets can be referenced in workflow files using the syntax ${{ secrets.SECRET_NAME }}.

There is a distinction between secrets at the repository, environment and organization level. In general, you should store secrets at the repository or organization level, depending on your security posture. It is only recommended that you utilize environment-level secrets if your Docker credentials differ per environment (dev, staging, etc.).

Examples

Docker Hub

• Save your Docker Hub username (DOCKER_USERNAME) and password (DOCKER_PASSWORD) as secrets in your GitHub repo
• Modify sample below and include in your workflow .github/workflows/*.yml file

uses: mr-smithers-excellent/docker-build-push@v6
with:
  image: docker-hub-repo/image-name
  registry: docker.io
  username: ${{ secrets.DOCKER_USERNAME }}
  password: ${{ secrets.DOCKER_PASSWORD }}

Google Container Registry (GCR)

• Create a service account with the ability to push to GCR (see configuring access control)
• Create and download JSON key for new service account
• Save content of .json file as a secret called DOCKER_PASSWORD in your GitHub repo
• Modify sample below and include in your workflow .github/workflows/*.yml file
• Ensure you set the username to _json_key

uses: mr-smithers-excellent/docker-build-push@v6
with:
  image: gcp-project/image-name
  registry: gcr.io
  username: _json_key
  password: ${{ secrets.DOCKER_PASSWORD }}

AWS Elastic Container Registry (ECR)

• Create an IAM user with the ability to push to ECR (see example policies)
• Create and download access keys
• Save AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as secrets in your GitHub repo
• Ensure the repo you are trying to push to already exists, if not create with aws ecr create-repository before pushing
• Modify sample below and include in your workflow .github/workflows/*.yml file

uses: mr-smithers-excellent/docker-build-push@v6
with:
  image: image-name
  registry: [aws-account-number].dkr.ecr.[region].amazonaws.com
env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

GitHub Container Registry

• GitHub recently migrated their container registry from docker.pkg.github.com to ghcr.io
• It is assumed you'll be pushing the image to a repo inside your GitHub organization, unless you set githubOrg
• If using ghcr.io, provide the image name in ghcr.io/OWNER/IMAGE_NAME format
• If using docker.pkg.github.com, provide the image name in docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME format
• Provide either the ${{ github.actor }} or an alternate username for Docker login (with associated token below)
• Pass the default GitHub Actions token or custom secret with proper push permissions

New ghcr.io

uses: mr-smithers-excellent/docker-build-push@v6
with:
  image: image-name
  registry: ghcr.io
  githubOrg: override-org # optional
  username: ${{ secrets.GHCR_USERNAME }}
  password: ${{ secrets.GHCR_TOKEN }}

Legacy docker.pkg.github.com

uses: mr-smithers-excellent/docker-build-push@v6
with:
  image: github-repo/image-name
  registry: docker.pkg.github.com
  username: ${{ github.actor }}
  password: ${{ secrets.GITHUB_TOKEN }}

Auto-tagging with GitOps

By default, if you do not pass a tags input this action will use an algorithm based on the state of your git repo to determine the Docker image tag(s). This is designed to enable developers to more easily use GitOps in their CI/CD pipelines. Below is a table detailing how the GitHub trigger (branch or tag) determines the Docker tag(s).

BuildKit support

Enables Docker BuildKit

steps:
  - uses: actions/checkout@v3
    name: Check out code

  - uses: mr-smithers-excellent/docker-build-push@v6
    name: Build & push Docker image
    with:
      image: repo/image
      registry: docker.io
      enableBuildKit: true
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}

Multi-platform builds

Enables multi-platform builds with the default docker-container driver

steps:
  - uses: actions/checkout@v3
    name: Check out code

  - uses: mr-smithers-excellent/docker-build-push@v6
    name: Build & push Docker image
    with:
      image: repo/image
      registry: docker.io
      multiPlatform: true
      platform: linux/amd64,linux/arm64,linux/arm/v7
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}

Enables multi-platform builds with custom driver

steps:
  - uses: actions/checkout@v3
    name: Check out code

  # Required when overrideDriver is set to true
  - uses: docker/setup-buildx-action@v2
    name: Customize Docker driver
    with:
      driver-opts: image=moby/buildkit:v0.11.0

  - uses: mr-smithers-excellent/docker-build-push@v6
    name: Build & push Docker image
    with:
      image: repo/image
      registry: docker.io
      multiPlatform: true
      platform: linux/amd64,linux/arm64,linux/arm/v7
      overrideDriver: true
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}