docker / Build Push Action

Upgrade from v1

v2 of this action includes significant updates and now uses Docker Buildx. It's also rewritten as a typescript-action to be as close as possible of the GitHub Runner during its execution.

Upgrade notes with many usage examples have been added to handle most use cases but v1 is still available through releases/v1 branch.

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.

💡 See also:

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

• Usage
  • Git context
  • Path context
• Advanced usage
  • Multi-platform image
  • Secrets
  • Isolated builders
  • Push to multi-registries
  • Cache
    • Registry cache
    • GitHub cache
  • Local registry
  • Export image to Docker
  • Handle tags and labels
  • Update DockerHub repo description
• Customizing
  • inputs
  • outputs
• Troubleshooting
• Keep up-to-date with GitHub Dependabot
• Limitation

Usage

By default, this action uses the Git context so you don't need to use the actions/checkout action to checkout 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>.

Be careful because any file mutation in the steps that precede the build step will be ignored 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.

In the examples below we are 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

name: ci

on:
  push:
    branches:
      - 'master'

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: Set up QEMU
        uses: docker/[email protected]
      -
        name: Set up Docker Buildx
        uses: docker/[email protected]
      -
        name: Login to DockerHub
        uses: docker/[email protected] 
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Build and push
        id: docker_build
        uses: docker/[email protected]
        with:
          push: true
          tags: user/app:latest
      -
        name: Image digest
        run: echo ${{ steps.docker_build.outputs.digest }}

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
        id: docker_build
        uses: docker/[email protected]
        with:
          push: true
          tags: user/app:latest
          secrets: |
            GIT_AUTH_TOKEN=${{ secrets.MYTOKEN }}

⚠️ Subdir for Git context is not yet supported (moby/buildkit#1684) but you can use the path context in the meantime. More info on Docker docs website.

Path context

name: ci

on:
  push:
    branches:
      - 'master'

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/[email protected]
      -
        name: Set up QEMU
        uses: docker/[email protected]
      -
        name: Set up Docker Buildx
        uses: docker/[email protected]
      -
        name: Login to DockerHub
        uses: docker/[email protected]
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Build and push
        uses: docker/[email protected]
        with:
          context: .
          push: true
          tags: user/app:latest

Advanced usage

• Multi-platform image
• Secrets
• Isolated builders
• Push to multi-registries
• Cache
  • Registry cache
  • GitHub cache
• Local registry
• Export image to Docker
• 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

outputs

Following outputs are available

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"

Limitation

This action is only available for Linux virtual environments.