build-push-action/README.md

About

GitHub Action to build and push Docker images with Buildx with full support of the features provided by Moby BuildKit builder toolkit. This includes multi-platform build, secrets, remote cache, etc. and different builder deployment/namespacing options.

---

• Usage
  • Git context
  • Path context
• Advanced usage
  • Multi-platform image
  • Secrets
  • Isolated builders
  • Push to multi-registries
  • Copy between registries
  • Cache
  • Local registry
  • Export image to Docker
  • Share built image between jobs
  • Test your image before pushing it
  • Handle tags and labels
  • Update DockerHub repo description
• Customizing
  • inputs
  • outputs
• Troubleshooting
• Keep up-to-date with GitHub Dependabot

Usage

In the examples below we are also using 3 other actions:

• setup-buildx action will create and boot a builder using by default the docker-container builder driver. This is not required but recommended using it to be able to build multi-platform images, export cache, etc.
• setup-qemu action can be useful if you want to add emulation support with QEMU to be able to build against more platforms.
• login action will take care to log in against a Docker registry.

Git context

By default, this action uses the Git context so you don't need to use the actions/checkout action to check out the repository because this will be done directly by BuildKit.

The git reference will be based on the event that triggered your workflow and will result in the following context: https://github.com/<owner>/<repo>.git#<ref>.

name: ci

on:
  push:
    branches:
      - 'main'

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v1
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      -
        name: Login to DockerHub
        uses: docker/login-action@v1 
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Build and push
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: user/app:latest

Be careful because any file mutation in the steps that precede the build step will be ignored, including processing of the .dockerignore file since the context is based on the Git reference. However, you can use the Path context using the context input alongside the actions/checkout action to remove this restriction.

Default Git context can also be provided using the Handlebars template expression {{defaultContext}}. Here we can use it to provide a subdirectory to the default Git context:

      -
        name: Build and push
        uses: docker/build-push-action@v2
        with:
          context: "{{defaultContext}}:mysubdir"
          push: true
          tags: user/app:latest

⚠️ Subdirectory for Git context is not yet available for the buildx docker driver.

Building from the current repository automatically uses the GitHub Token so it does not need to be passed. If you want to authenticate against another private repository, you have to use a secret named GIT_AUTH_TOKEN to be able to authenticate against it with buildx:

      -
        name: Build and push
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: user/app:latest
          secrets: |
            GIT_AUTH_TOKEN=${{ secrets.MYTOKEN }}            

Path context

name: ci

on:
  push:
    branches:
      - 'main'

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v2
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v1
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      -
        name: Login to DockerHub
        uses: docker/login-action@v1
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Build and push
        uses: docker/build-push-action@v2
        with:
          context: .
          push: true
          tags: user/app:latest

Advanced usage

• Multi-platform image
• Secrets
• Isolated builders
• Push to multi-registries
• Copy between registries
• Cache
• Local registry
• Export image to Docker
• Share built image between jobs
• Test your image before pushing it
• Handle tags and labels
• Update DockerHub repo description

Customizing

inputs

Following inputs can be used as step.with keys

List type is a newline-delimited string

cache-from: |
  user/app:cache
  type=local,src=path/to/dir  

CSV type is a comma-delimited string

tags: name/app:latest,name/app:1.0.0

Name	Type	Description
allow	List/CSV	List of extra privileged entitlement (e.g., network.host,security.insecure)
builder	String	Builder instance (see setup-buildx action)
build-args	List	List of build-time variables
cache-from	List	List of external cache sources (e.g., type=local,src=path/to/dir)
cache-to	List	List of cache export destinations (e.g., type=local,dest=path/to/dir)
cgroup-parent¹	String	Optional parent cgroup for the container used in the build
context	String	Build's context is the set of files located in the specified PATH or URL (default Git context)
file	String	Path to the Dockerfile. (default {context}/Dockerfile)
labels	List	List of metadata for an image
load	Bool	Load is a shorthand for --output=type=docker (default false)
network	String	Set the networking mode for the RUN instructions during build
no-cache	Bool	Do not use cache when building the image (default false)
outputs	List	List of output destinations (format: type=local,dest=path)
platforms	List/CSV	List of target platforms for build
pull	Bool	Always attempt to pull a newer version of the image (default false)
push	Bool	Push is a shorthand for --output=type=registry (default false)
secrets	List	List of secrets to expose to the build (e.g., key=string, GIT_AUTH_TOKEN=mytoken)
secret-files	List	List of secret files to expose to the build (e.g., key=filename, MY_SECRET=./secret.txt)
shm-size¹	String	Size of /dev/shm (e.g., 2g)
ssh	List	List of SSH agent socket or keys to expose to the build
tags	List/CSV	List of tags
target	String	Sets the target stage to build
ulimit¹	List	Ulimit options (e.g., nofile=1024:1024)
github-token	String	GitHub Token used to authenticate against a repository for Git context (default ${{ github.token }})

¹ cgroup-parent, shm-size and ulimit are only available using moby/buildkit:master as builder image atm:

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v1
  with:
  driver-opts: |
    image=moby/buildkit:master    

outputs

Following outputs are available

Name	Type	Description
digest	String	Image content-addressable identifier also called a digest
metadata	JSON	Build result metadata

Troubleshooting

See TROUBLESHOOTING.md

Keep up-to-date with GitHub Dependabot

Since Dependabot has native GitHub Actions support, to enable it on your GitHub repo all you need to do is add the .github/dependabot.yml file:

version: 2
updates:
  # Maintain dependencies for GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"