Skip to content

Home / Blog / Caching

docker/build-push-action and setup-buildx-action: inputs, cache types, versions

Every input of docker/build-push-action v7 and setup-buildx-action v4, all six cache types with a workflow we ran, and what changed in each version.

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.

In short
  • 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.

ReleaseDateWhat changed
build-push-action v7.4.015 Sep 2026The current release. Its notes: prevents workflow command injection in metadata logs, and uses a shared error helper.
build-push-action v7.0.05 Mar 2026Node 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.212 Feb 2026The last v6 release; v6 runs on Node 20.
setup-buildx-action v4.4.116 Sep 2026The current release.
setup-buildx-action v4.0.05 Mar 2026Node 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.019 Dec 2025The 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.

InputDefaultWhat it does
add-hostsExtra host-to-IP mappings for the build (docker:10.180.0.1)
allowExtra privileged entitlements (network.host, security.insecure)
annotationsAnnotations to set on the image
attestsAttestation parameters (type=sbom,generator=image)
build-argsBuild-time variables
build-contextsAdditional build contexts (name=path)
builderThe builder instance to use
cache-fromExternal cache sources (type=gha, type=registry,ref=..., type=local,src=...)
cache-toCache export destinations (type=gha,mode=max and the others below)
callHow the build is evaluated (for example check)
cgroup-parentParent cgroup for the container used in the build
contextGit contextThe set of files the build can read: a path or a URL
file{context}/DockerfilePath to the Dockerfile
labelsMetadata labels for the image
loadfalseLoad the result into the local Docker image store (shorthand for --output=type=docker)
networkNetworking mode for RUN instructions
no-cachefalseDo not use cache when building the image
no-cache-filtersStages that must not be cached
outputsOutput destinations (type=local,dest=path)
platformsTarget platforms (linux/amd64,linux/arm64)
provenanceProvenance attestation (shorthand for --attest=type=provenance)
pullfalseAlways attempt to pull all referenced images
pushfalsePush the result to the registry (shorthand for --output=type=registry)
sbomSBOM attestation (shorthand for --attest=type=sbom)
secretsSecrets to expose to the build (key=string)
secret-envsSecrets taken from environment variables (key=envname)
secret-filesSecrets taken from files (key=filename)
shm-sizeSize of /dev/shm (2g)
sshSSH agent sockets or keys to expose to the build
tagsImage tags
targetThe stage of a multi-stage Dockerfile to build
ulimitUlimit options (nofile=1024:1024)
github-tokengithub.tokenToken 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:

VariableDefaultWhat it does
DOCKER_BUILD_CHECKS_ANNOTATIONStrueIf false, no GitHub annotations are made for build checks
DOCKER_BUILD_SUMMARYtrueIf false, the job summary of the build is not written
DOCKER_BUILD_RECORD_UPLOADtrueIf false, the build record is not uploaded as an artifact
DOCKER_BUILD_RECORD_RETENTION_DAYSDays 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.

InputDefaultWhat it does
versionThe Buildx version to install (v0.3.0, latest, or a Git URL); empty uses the one on the runner
driverdocker-containerThe builder driver
driver-optsDriver options (image=moby/buildkit:master, network=host)
buildkitd-flagsFlags for the BuildKit daemon; setting this resets the default flags
buildkitd-configPath to a BuildKit daemon config file
buildkitd-config-inlineThe same config, inline; exclusive with buildkitd-config
usetrueSwitch to this builder
nameBuilder name; one is generated when empty, and an existing one of that name is reused
endpointDocker socket address or context
platformsFixed platforms for the node; they take priority over the detected ones
appendMore nodes to add to the builder
keep-statefalseKeep BuildKit state on cleanup; only useful on persistent self-hosted runners
cache-binarytrueCache the Buildx binary in the GitHub Actions cache
cleanuptrueRemove 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.

TypeWhere the cache livesMain parameters of cache-toThe builder it needs
ghaGitHub's Actions cachescope, mode, ignore-error, timeoutDefault docker driver only with the containerd image store
registryA separate image in a registryref, mode, compression, oci-mediatypes, ignore-errorDefault docker driver only with the containerd image store
inlineInside the image you pushnoneDefault docker driver only with the containerd image store
localA directory, in an OCI image layoutdest, tag, mode, compression, reset, ignore-errorDefault docker driver only with the containerd image store
s3An S3 bucket or an S3-compatible serverregion, bucket, name, endpoint_url, use_path_style, modeNot with the default docker driver
azblobAzure Blob Storagename, account_url, secret_access_key, modeNot 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

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.

Move your CI onto our runners with one line

Change one line, watch your own build, then decide.

Connect GitHub

Card required. You pay only for the minutes your jobs run.

.github/workflows/ci.yml
jobs: test:removed: runs-on: ubuntu-latestadded: runs-on: runnersio-4vcpu-ubuntu-2604 steps: - uses: actions/checkout@v4 - run: make testadded: build:added: runs-on: runnersio-32vcpu-ubuntu-2604