docker/build-push-action is at v7.4.0 and docker/setup-buildx-action at v4.4.1, as of the date this post was last checked. Both moved to Node 24 on 5 March 2026, so the runner must be version 2.327.1 or later. Create a builder with setup-buildx-action, then build and push with build-push-action, and add cache-from: type=gha and cache-to: type=gha,mode=max to keep layers between runs. Our Docker build cache guide has the full setup.
- docker/build-push-action is at v7.4.0 and docker/setup-buildx-action at v4.4.1; both moved to Node 24 on 5 March 2026 and need runner 2.327.1 or later.
- build-push-action takes 33 inputs and setup-buildx-action 14; all are optional.
- cache-from and cache-to take six types: gha, registry, inline, local, s3 and azblob; we ran a workflow for each.
- GitHub switched off the old Actions cache service on 15 April 2025, so Buildx 0.21.0 or later is needed for type=gha.
- mode=min caches only the final image's layers, and mode=max caches intermediate stages too.
This page lists every input of both actions, every cache type with a workflow we ran, and what changed between versions. Every figure was read from the actions’ own repositories and Docker’s documentation on the date this post was last checked. The workflows ran on GitHub-hosted runners in a public repository, with each action pinned to a commit there and shown here by its tag. The one other difference is the build context: we built a three-line Dockerfile from a folder, and the samples below say context: ..
What are the current versions of build-push-action and setup-buildx-action?
v7 of the build action and v4 of the setup action are current. The v7 build action and the v4 setup action moved to Node 24, and v4 of the setup action dropped three deprecated inputs, so an upgrade is a check of the runner version and of any input you still pass.
| Release | Date | What changed |
|---|---|---|
| build-push-action v7.4.0 | 15 Sep 2026 | The current release. Its notes: prevents workflow command injection in metadata logs, and uses a shared error helper. |
| build-push-action v7.0.0 | 5 Mar 2026 | Node 24, so the runner must be 2.327.1 or later. Removes the DOCKER_BUILD_NO_SUMMARY and DOCKER_BUILD_EXPORT_RETENTION_DAYS variables and legacy export-build support in the summary. |
| build-push-action v6.19.2 | 12 Feb 2026 | The last v6 release; v6 runs on Node 20. |
| setup-buildx-action v4.4.1 | 16 Sep 2026 | The current release. |
| setup-buildx-action v4.0.0 | 5 Mar 2026 | Node 24, so the runner must be 2.327.1 or later. Removes the deprecated inputs config, config-inline and install. |
| setup-buildx-action v3.12.0 | 19 Dec 2025 | The last v3 release; it deprecated the install input. v3 runs on Node 20. |
A major tag such as @v7 follows the newest release of that major, and the actions’ own README uses it. GitHub recommends pinning an action to a full-length commit SHA instead, which is what the workflows in our repository do.
How do I build and push an image to GHCR from GitHub Actions?
Log in to ghcr.io with the repository’s own token, set up a builder, and build with push: true. The job needs packages: write. A package published from a workflow is linked to that repository automatically, but GitHub warns the token cannot push to a package that already exists in your namespace without being connected to the repository.
name: ci
on:
push:
jobs:
docker:
runs-on: ubuntu-24.04
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v7
- uses: docker/login-action@v4
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
To push to Docker Hub instead, change the login step’s registry and credentials as the action’s README shows. We did not run that one: it needs a Docker Hub token, and GHCR works with the token every workflow already has. With no context, the action builds the Git context of the event and needs no checkout, but then files changed by earlier steps, and the .dockerignore, are ignored; the README says so.
What inputs does docker/build-push-action take?
Thirty-three inputs, all optional. Lists are newline-delimited, and the ones the README marks as CSV (such as tags and platforms) also take commas. The defaults below are the action’s own.
| Input | Default | What it does |
|---|---|---|
| add-hosts | Extra host-to-IP mappings for the build (docker:10.180.0.1) | |
| allow | Extra privileged entitlements (network.host, security.insecure) | |
| annotations | Annotations to set on the image | |
| attests | Attestation parameters (type=sbom,generator=image) | |
| build-args | Build-time variables | |
| build-contexts | Additional build contexts (name=path) | |
| builder | The builder instance to use | |
| cache-from | External cache sources (type=gha, type=registry,ref=..., type=local,src=...) | |
| cache-to | Cache export destinations (type=gha,mode=max and the others below) | |
| call | How the build is evaluated (for example check) | |
| cgroup-parent | Parent cgroup for the container used in the build | |
| context | Git context | The set of files the build can read: a path or a URL |
| file | {context}/Dockerfile | Path to the Dockerfile |
| labels | Metadata labels for the image | |
| load | false | Load the result into the local Docker image store (shorthand for --output=type=docker) |
| network | Networking mode for RUN instructions | |
| no-cache | false | Do not use cache when building the image |
| no-cache-filters | Stages that must not be cached | |
| outputs | Output destinations (type=local,dest=path) | |
| platforms | Target platforms (linux/amd64,linux/arm64) | |
| provenance | Provenance attestation (shorthand for --attest=type=provenance) | |
| pull | false | Always attempt to pull all referenced images |
| push | false | Push the result to the registry (shorthand for --output=type=registry) |
| sbom | SBOM attestation (shorthand for --attest=type=sbom) | |
| secrets | Secrets to expose to the build (key=string) | |
| secret-envs | Secrets taken from environment variables (key=envname) | |
| secret-files | Secrets taken from files (key=filename) | |
| shm-size | Size of /dev/shm (2g) | |
| ssh | SSH agent sockets or keys to expose to the build | |
| tags | Image tags | |
| target | The stage of a multi-stage Dockerfile to build | |
| ulimit | Ulimit options (nofile=1024:1024) | |
| github-token | github.token | Token used to read the repository for a Git context |
It has three outputs: imageid, digest and metadata (the build result as JSON). Four environment variables change its behaviour:
| Variable | Default | What it does |
|---|---|---|
| DOCKER_BUILD_CHECKS_ANNOTATIONS | true | If false, no GitHub annotations are made for build checks |
| DOCKER_BUILD_SUMMARY | true | If false, the job summary of the build is not written |
| DOCKER_BUILD_RECORD_UPLOAD | true | If false, the build record is not uploaded as an artifact |
| DOCKER_BUILD_RECORD_RETENTION_DAYS | Days before the build-record artifact expires; unset or 0 follows the repository's retention setting |
One trap: the build record is uploaded as an artifact, so a later actions/download-artifact step with no name or pattern downloads it and, the README warns, fails unless it ignores !*.dockerbuild.
What inputs does docker/setup-buildx-action take?
Fourteen inputs, all optional, and the defaults are good for most builds. It installs or selects Buildx and creates a builder with the docker-container driver, which is what lets you build for several platforms and export a cache.
| Input | Default | What it does |
|---|---|---|
| version | The Buildx version to install (v0.3.0, latest, or a Git URL); empty uses the one on the runner | |
| driver | docker-container | The builder driver |
| driver-opts | Driver options (image=moby/buildkit:master, network=host) | |
| buildkitd-flags | Flags for the BuildKit daemon; setting this resets the default flags | |
| buildkitd-config | Path to a BuildKit daemon config file | |
| buildkitd-config-inline | The same config, inline; exclusive with buildkitd-config | |
| use | true | Switch to this builder |
| name | Builder name; one is generated when empty, and an existing one of that name is reused | |
| endpoint | Docker socket address or context | |
| platforms | Fixed platforms for the node; they take priority over the detected ones | |
| append | More nodes to add to the builder | |
| keep-state | false | Keep BuildKit state on cleanup; only useful on persistent self-hosted runners |
| cache-binary | true | Cache the Buildx binary in the GitHub Actions cache |
| cleanup | true | Remove temp files and the builder at the end of the job |
Its outputs are name, driver, platforms and nodes (JSON). The action file still lists endpoint, status and flags as deprecated outputs, to be replaced by nodes. Set buildkitd-flags and you lose the two default flags, --allow-insecure-entitlement security.insecure and --allow-insecure-entitlement network.host, unless you repeat them.
Which cache types can cache-from and cache-to use?
Six, and each is a type= in the same two inputs. Docker marks gha as beta, and s3 and azblob as experimental. The default docker driver can export the first four only with the containerd image store turned on, so create a builder with setup-buildx-action, as every sample here does.
| Type | Where the cache lives | Main parameters of cache-to | The builder it needs |
|---|---|---|---|
| gha | GitHub's Actions cache | scope, mode, ignore-error, timeout | Default docker driver only with the containerd image store |
| registry | A separate image in a registry | ref, mode, compression, oci-mediatypes, ignore-error | Default docker driver only with the containerd image store |
| inline | Inside the image you push | none | Default docker driver only with the containerd image store |
| local | A directory, in an OCI image layout | dest, tag, mode, compression, reset, ignore-error | Default docker driver only with the containerd image store |
| s3 | An S3 bucket or an S3-compatible server | region, bucket, name, endpoint_url, use_path_style, mode | Not with the default docker driver |
| azblob | Azure Blob Storage | name, account_url, secret_access_key, mode | Not with the default docker driver |
The samples show the steps after checkout and login. We ran each one twice in one job, on two fresh builders, and compared a timestamp the first build wrote into a layer. The same timestamp in the second image means the layer came from the cache; a miss would have made a new one. All six passed.
gha. Docker calls it the recommended cache inside GitHub Actions, as long as you stay within GitHub’s cache size and eviction limits. Its default scope is buildkit, and Docker warns that with one scope each build overwrites the previous one’s cache, so give each image its own, for example scope=app. The action fills in the cache URL and token for you.
steps:
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
cache-from: type=gha
cache-to: type=gha,mode=max
registry. The cache goes to its own image, so the image you ship carries no cache. The ref must differ from the tag you push to. If the ref does not exist yet, the import fails and the build carries on, which is what the first run does. Docker lists the same parameters for mode, compression and OCI media types.
steps:
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max
inline. The cache rides inside the image you push, so there is nothing else to store, and you read it back with type=registry pointed at the image. Docker says it does not scale with multi-stage builds, and it supports only min mode.
steps:
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:latest
cache-to: type=inline
local. A directory, which you persist yourself, here with actions/cache. Docker notes that exporting to a directory that already holds a cache leaves the old blobs behind, so the directory grows every run; adding reset=true to the export deletes them, and needs Buildx 0.35.0 or later. We ran the sample without it.
steps:
- uses: actions/cache@v6
with:
path: ${{ runner.temp }}/.buildx-cache
key: ${{ runner.os }}-buildx-${{ github.sha }}
restore-keys: |
${{ runner.os }}-buildx-
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
cache-from: type=local,src=${{ runner.temp }}/.buildx-cache
cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache,mode=max
s3 and azblob. These need a builder that is not the default driver, and Docker marks both experimental. We ran them against an S3-compatible test server (Adobe S3Mock) and Azure’s storage emulator (Azurite), started in the job, so the endpoint, the path-style setting and the credentials in the samples are the test servers’. For AWS S3 you give a real region and bucket, and Docker says the endpoint is optional. We have not run either against AWS or Azure.
env:
S3_ACCESS_KEY_ID: ${{ secrets.S3_ACCESS_KEY_ID }}
S3_SECRET_ACCESS_KEY: ${{ secrets.S3_SECRET_ACCESS_KEY }}
steps:
- name: Start an S3-compatible server (Adobe S3Mock) with a bucket
run: |
docker run -d --name s3mock --network host adobe/s3mock
until curl -fs http://127.0.0.1:9090/ >/dev/null; do sleep 1; done
curl -fsS -X PUT http://127.0.0.1:9090/buildcache
- uses: docker/setup-buildx-action@v4
with:
driver-opts: network=host
- uses: docker/build-push-action@v7
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
cache-from: type=s3,region=us-east-1,bucket=buildcache,name=app,endpoint_url=http://127.0.0.1:9090,use_path_style=true,access_key_id=${{ env.S3_ACCESS_KEY_ID }},secret_access_key=${{ env.S3_SECRET_ACCESS_KEY }}
cache-to: type=s3,region=us-east-1,bucket=buildcache,name=app,endpoint_url=http://127.0.0.1:9090,use_path_style=true,access_key_id=${{ env.S3_ACCESS_KEY_ID }},secret_access_key=${{ env.S3_SECRET_ACCESS_KEY }},mode=max
env:
AZURE_STORAGE_KEY: ${{ secrets.AZURE_STORAGE_KEY }}
steps:
- name: Start Azurite, the Azure Storage emulator
run: |
docker run -d --name azurite --network host mcr.microsoft.com/azure-storage/azurite azurite-blob --blobHost 127.0.0.1 --skipApiVersionCheck
- uses: docker/setup-buildx-action@v4
with:
driver-opts: network=host
- uses: docker/build-push-action@v7
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
cache-from: type=azblob,account_url=http://127.0.0.1:10000/devstoreaccount1,account_name=devstoreaccount1,container=buildcache,name=app,secret_access_key=${{ env.AZURE_STORAGE_KEY }}
cache-to: type=azblob,account_url=http://127.0.0.1:10000/devstoreaccount1,account_name=devstoreaccount1,container=buildcache,name=app,secret_access_key=${{ env.AZURE_STORAGE_KEY }},mode=max
Why did type=gha stop working in April 2025?
GitHub moved the Actions cache to a new service and switched the old one off on 15 April 2025, with two brownouts first. A cache client built for the old API, which GitHub named as including Docker with the Actions cache as a backend, then fails with This legacy service is shutting down.
Docker’s fix is a version bump: Buildx 0.21.0 or later, BuildKit 0.20.0 or later, Docker Compose 2.33.1 or later, or Docker Engine 28.0.0 or later with the containerd image store. On GitHub-hosted runners Docker says Buildx and BuildKit are already current. On a self-hosted runner, setup-buildx-action with version: latest brings Buildx up to date, and GitHub also lists a runner older than 2.320.1 as one that may still reach the old service.
There is a newer change. On 26 June 2026 GitHub announced that it issues a read-only cache token to workflows that an outsider can trigger and that run against the default branch: pull_request_target, issue_comment and forks’ workflow_run cascades. push, schedule, workflow_dispatch and ordinary pull_request runs keep write access, though Docker notes that a pull_request run of type closed after a merge uses the target branch and is read-only. In a read-only run, cache-to: type=gha can fail after the image has been pushed, with failed to reserve cache. Docker’s advice is to keep cache-from, drop cache-to there, and let a push workflow fill the cache. ignore-error=true hides the failure but saves nothing.
What is the difference between mode=min and mode=max?
min, the default, caches only the layers of the final image. max also caches the layers of intermediate stages. Docker says min is typically smaller and max more likely to hit, and Docker says the registry backend can cache multi-stage builds in max mode instead of only the final stage. How much it matters, in seconds, for three real Dockerfiles is in the measurement of the four cache types, and the concepts, including layer order, are in the Docker build cache post.
How do I build for more than one platform?
List the platforms, and add docker/setup-qemu-action as the action’s README suggests. The sample below pushed a tag that listed both linux/amd64 and linux/arm64. We also ran it without the QEMU step, on a GitHub-hosted runner, and it pushed the same two platforms: Docker says official BuildKit releases bundle QEMU emulators, so in most cases you do not need to install them yourself, and keeps the step for when emulation fails. Emulating arm64 is slower than building on an ARM machine, and Docker says it can be much slower for compilation; for how ARM runners work with private repositories, see the ARM64 runners post.
steps:
- uses: docker/setup-qemu-action@v4
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
platforms: linux/amd64,linux/arm64
push: true
tags: ghcr.io/${{ github.repository }}:latest
If the image is for a runners.io job, our page on a Docker layer cache for GitHub Actions and the layer cache documentation say what is kept between jobs without any cache-to.
Sources
- docker/build-push-action releases (github.com)
- docker/build-push-action README (v7.4.0) (github.com)
- docker/build-push-action action.yml (v7.4.0) (github.com)
- docker/setup-buildx-action releases (github.com)
- docker/setup-buildx-action action.yml (v4.4.1) (github.com)
- docker/setup-buildx-action README (v4.4.1) (github.com)
- Cache storage backends (Docker) (docs.docker.com)
- GitHub Actions cache backend (Docker) (docs.docker.com)
- Registry cache (Docker) (docs.docker.com)
- Inline cache (Docker) (docs.docker.com)
- Local cache (Docker) (docs.docker.com)
- Amazon S3 cache (Docker) (docs.docker.com)
- Azure Blob Storage cache (Docker) (docs.docker.com)
- Cache management with GitHub Actions (Docker) (docs.docker.com)
- Multi-platform builds (Docker) (docs.docker.com)
- Notification of upcoming breaking changes in GitHub Actions (GitHub changelog, 20 March 2025) (github.blog)
- Read-only Actions cache for untrusted triggers (GitHub changelog, 26 June 2026) (github.blog)
- Publishing Docker images (GitHub) (docs.github.com)
- Working with the Container registry (GitHub) (docs.github.com)
- Secure use reference (GitHub) (docs.github.com)
- BuildKit README: Azure Blob Storage cache (github.com)
- The workflows we ran (runners-io/ci-measurements, study D1) (github.com)
Frequently asked questions
What are the current versions of build-push-action and setup-buildx-action?
docker/build-push-action v7.4.0, released 15 September 2026, and docker/setup-buildx-action v4.4.1, released 16 September 2026. Both run on Node 24 since their March 2026 majors, so the runner must be 2.327.1 or later.
How do I build and push an image to GHCR from GitHub Actions?
Give the job packages: write, log in to ghcr.io with docker/login-action and the GITHUB_TOKEN as the password, set up a builder, then run build-push-action with push: true and a tag under ghcr.io. A package published from a workflow is linked to its repository.
Which cache types can cache-from and cache-to use?
gha, registry, inline, local, s3 and azblob. The default docker driver exports the first four only with the containerd image store, and not s3 or azblob, so create a builder with setup-buildx-action. Docker recommends gha inside GitHub Actions within GitHub's limits.
Why did type=gha stop working in April 2025?
GitHub switched off the old Actions cache service on 15 April 2025. Clients built for it fail with a legacy-service error. Use Buildx 0.21.0 or later and BuildKit 0.20.0 or later; GitHub-hosted runners already have them.
What is the difference between mode=min and mode=max?
min, the default, caches only the layers that end up in the final image. max also caches the layers of intermediate stages. Docker says min is typically smaller and max more likely to hit. The inline type supports min only.