docker/build-push-action

Build and push a Docker image using Buildx, with cache and multi-platform support.

Official actionCategory: Docker & ContainersLatest v6View on GitHub

What it does

docker/build-push-action wraps docker buildx build for CI. It builds from a Dockerfile and can push to any registry, emit an image digest, and cache layers between runs.

It is almost always used after docker/setup-buildx-action (and docker/login-action to push), with docker/metadata-action supplying the tags and labels.

Usage

workflow (.yml)

steps:
  - uses: actions/checkout@v4
  - uses: docker/setup-buildx-action@v3
  - uses: docker/login-action@v3
    with:
      username: ${{ secrets.DOCKERHUB_USERNAME }}
      password: ${{ secrets.DOCKERHUB_TOKEN }}
  - uses: docker/build-push-action@v6
    with:
      push: true
      tags: myorg/app:latest
      cache-from: type=gha
      cache-to: type=gha,mode=max

Inputs

Input	Description	Default	Required
`context`	Build context path or URL.	`git context`	No
`file`	Path to the Dockerfile.	`Dockerfile`	No
`push`	Push the image to the registry after building.	`false`	No
`tags`	Comma or newline separated list of image tags.	-	No
`platforms`	Target platforms, e.g. linux/amd64,linux/arm64.	`host`	No
`cache-from`	External cache source, e.g. type=gha.	-	No
`cache-to`	Cache export destination, e.g. type=gha,mode=max.	-	No
`build-args`	Build-time variables passed to the Dockerfile.	-	No

Outputs

Output	Description
`imageid`	The built image ID.
`digest`	The image digest after push.
`metadata`	Build result metadata (JSON).

Notes

Use cache-from: type=gha and cache-to: type=gha,mode=max to reuse layers across runs via the GitHub Actions cache.

Multi-platform builds require docker/setup-qemu-action for the non-native architecture.

Common errors

buildx: command not found or a Buildx driver error means docker/setup-buildx-action did not run first. Add it before this step.
denied: requested access to the resource is denied on push means docker/login-action did not authenticate, or the token lacks push scope.
A slow build that never reuses layers usually has no cache-from/cache-to configured.

Security and pinning

Pin build-push-action to a commit SHA.
Pass registry credentials from secrets via docker/login-action; never bake them into the image or build-args (build args are visible in the image history).

Alternatives and related

docker/setup-buildx-actionSet up Docker Buildx so a workflow can do multi-platform builds and layer caching. docker/login-actionLog in to Docker Hub, GHCR, ECR, or any registry before pushing an image. docker/metadata-actionGenerate Docker tags and OCI labels automatically from git refs and events.

Frequently asked questions

How do I cache Docker layers in GitHub Actions?

Set cache-from: type=gha and cache-to: type=gha,mode=max. This stores layers in the Actions cache and reuses them on later runs.

How do I build for arm64 and amd64?

Add docker/setup-qemu-action, then set platforms: linux/amd64,linux/arm64 on build-push-action.