About

GitHub Action to build and push Docker images with Buildx.

💡 See also:

• login action
• setup-buildx action
• setup-qemu action

---

• Usage
  • Git context
  • Path context
  • Isolated builders
  • Multi-platform image
  • Local registry
  • Leverage GitHub cache
  • Tags handling
  • Complete workflow
  • Update DockerHub repo description
• Customizing
  • inputs
  • outputs
• Keep up-to-date with GitHub Dependabot
• Limitation

Usage

This action uses our setup-buildx action that extends the docker build command named buildx with the full support of the features provided by Moby BuildKit builder toolkit. This includes multi-arch build, build-secrets, remote cache, etc. and different builder deployment/namespacing options.

Git context

The default behavior of this action is to use the Git context invoked by your workflow (https://github.com/owner/repo#ref).

name: ci

on:
  push:
    branches: master

jobs:
  main:
    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
        id: docker_build
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: user/app:latest
      -
        name: Image digest
        run: echo ${{ steps.docker_build.outputs.digest }}

If you use this action in a private repository, you have to pass the GitHub Token as a secret named GIT_AUTH_TOKEN to be able to authenticate against it with buildx:

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

Path context

You can also use the PATH context alongside the actions/checkout action.

name: ci

on:
  push:
    branches: master

jobs:
  path-context:
    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: .
          file: ./Dockerfile
          platforms: linux/amd64,linux/arm64,linux/386
          push: true
          tags: user/app:latest

Isolated builders

name: ci

on:
  push:
    branches: master

jobs:
  multi-builders:
    runs-on: ubuntu-latest
    steps:
      -
        uses: docker/setup-buildx-action@v1
        id: builder1
      -
        uses: docker/setup-buildx-action@v1
        id: builder2
      -
        name: Builder 1 name
        run: echo ${{ steps.builder1.outputs.name }}
      -
        name: Builder 2 name
        run: echo ${{ steps.builder2.outputs.name }}
      -
        name: Build against builder1
        uses: docker/build-push-action@v2
        with:
          builder: ${{ steps.builder1.outputs.name }}
          target: mytarget1
      -
        name: Build against builder2
        uses: docker/build-push-action@v2
        with:
          builder: ${{ steps.builder2.outputs.name }}
          target: mytarget2

Multi-platform image

name: ci

on:
  push:
    branches: master

jobs:
  multi:
    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: .
          file: ./Dockerfile
          platforms: linux/386,linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/ppc64le,linux/s390x
          push: true
          tags: |
            user/app:latest
            user/app:1.0.0            

Local registry

For testing purposes you may need to create a local registry to push images into.

name: ci

on:
  push:
    branches: master

jobs:
  local-registry:
    runs-on: ubuntu-latest
    services:
      registry:
        image: registry:2
        ports:
          - 5000:5000
    steps:
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v1
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
        with:
          driver-opts: network=host
      -
        name: Build and push to local registry
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: localhost:5000/name/app:latest
      -
        name: Inspect
        run: |
          docker buildx imagetools inspect localhost:5000/name/app:latest          

Leverage GitHub cache

You can leverage GitHub cache using actions/cache with this action.

name: ci

on:
  push:
    branches: master

jobs:
  github-cache:
    runs-on: ubuntu-latest
    steps:
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      -
        name: Cache Docker layers
        uses: actions/cache@v2
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-            
      -
        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
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache

Tags handling

If you come from v1 and you want an "automatic" tag management through Git reference, you will have to do it in a dedicated step for now.

The workflow below with the Prepare step will generate a tags output:

• On pull_request event with refs/pull/2/merge ref and a123b57 sha:
  • user/app:pr-2
• On push event with refs/heads/master ref and 676cae2 sha:
  • user/app:sha-676cae2
  • user/app:edge
• On push event with refs/heads/dev ref and cf20257 sha:
  • user/app:sha-cf20257
  • user/app:dev
• On push tags event with refs/tags/v1.2.3 ref and 9258794 sha:
  • user/app:sha-9258794
  • user/app:v1.2.3
  • user/app:v1.2
  • user/app:v1
  • user/app:latest

name: ci

on:
  push:
    branches: master
    tags:
      - 'v*.*.*'
  pull_request:
    branches: master

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v2
      -
        name: Prepare
        id: prep
        run: |
          DOCKER_IMAGE=name/app
          VERSION=edge
          if [[ $GITHUB_REF == refs/tags/* ]]; then
            VERSION=${GITHUB_REF#refs/tags/}
          fi
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            TAGS="${DOCKER_IMAGE}:pr-${{ github.event.number }}"
          else
            TAGS="${DOCKER_IMAGE}:${VERSION}"
            TAGS="${DOCKER_IMAGE}:sha-${GITHUB_SHA::8}"
          fi
          if [[ $VERSION =~ ^v[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
            MINOR=${VERSION%.*}
            MAJOR=${MINOR%.*}
            TAGS="$TAGS,${DOCKER_IMAGE}:${MINOR},${DOCKER_IMAGE}:${MAJOR},${DOCKER_IMAGE}:latest"
          fi
          echo ::set-output name=tags::${TAGS}          
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      -
        name: Build and push
        id: docker_build
        uses: docker/build-push-action@v2
        with:
          context: .
          file: ./Dockerfile
          tags: ${{ steps.prep.outputs.tags }}

Complete workflow

• On pull_request event, Docker image name/app:edge is built.
• On push event, Docker image name/app:edge is built and pushed to DockerHub.
• On schedule event, Docker image name/app:nightly is built and pushed to DockerHub.
• On push tags event, Docker image name/app:<version> and name/app:latest is built and pushed to DockerHub.

name: ci

on:
  schedule:
    - cron: '0 10 * * *' # everyday at 10am
  push:
    branches: master
    tags:
      - 'v*.*.*'
  pull_request:
    branches: master

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v2
      -
        name: Prepare
        id: prep
        run: |
          DOCKER_IMAGE=name/app
          VERSION=edge
          if [[ $GITHUB_REF == refs/tags/* ]]; then
            VERSION=${GITHUB_REF#refs/tags/}
          fi
          if [ "${{ github.event_name }}" = "schedule" ]; then
            VERSION=nightly
          fi
          TAGS="${DOCKER_IMAGE}:${VERSION}"
          if [[ $VERSION =~ ^v[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
            TAGS="$TAGS,${DOCKER_IMAGE}:latest"
          fi
          echo ::set-output name=tags::${TAGS}          
      -
        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
        if: github.event_name != 'pull_request'
        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: .
          file: ./Dockerfile
          platforms: linux/amd64,linux/arm64,linux/386
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.prep.outputs.tags }}

Update DockerHub repo description

You can update the Docker Hub repository description using a third-party action called Docker Hub Description with this action.

name: ci

on:
  push:
    branches: master

jobs:
  main:
    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
      -
        name: Update repo description
        uses: peter-evans/dockerhub-description@v2
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
          DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
          DOCKERHUB_REPOSITORY: user/app

Customizing

inputs

Following inputs can be used as step.with keys

Name	Type	Description
builder	String	Builder instance (see setup-buildx action)
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 Dockerfile)
build-args	List	List of build-time variables
labels	List	List of metadata for an image
tags	List	List of tags
pull	Bool	Always attempt to pull a newer version of the image (default false)
target	String	Sets the target stage to build
allow	List	List of extra privileged entitlement (eg. network.host,security.insecure)
no-cache	Bool	Do not use cache when building the image (default false)
platforms	List	List of target platforms for build
load	Bool	Load is a shorthand for --output=type=docker (default false)
push	Bool	Push is a shorthand for --output=type=registry (default false)
outputs	CSV	List of output destinations (format: type=local,dest=path)
cache-from	CSV	List of external cache sources (eg. type=local,src=path/to/dir)
cache-to	CSV	List of cache export destinations (eg. type=local,dest=path/to/dir)
secrets	CSV	List of secrets to expose to the build (eg. key=value, GIT_AUTH_TOKEN=mytoken)

List type can be a comma or newline-delimited string

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

tags: |
  name/app:latest
  name/app:1.0.0  

CSV type must be a newline-delimited string

cache-from: user/app:cache

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

outputs

Following outputs are available

Name	Type	Description
digest	String	Image content-addressable identifier also called a digest

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"

Limitation

This action is only available for Linux virtual environments.