# 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.

By Grant Unwin, published 2026-11-05. Checked against Docker's and GitHub's documentation and the actions' repositories on 2026-11-17. The web page: https://www.runners.io/blog/docker-build-push-action-setup-buildx-action-reference

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](https://www.runners.io/blog/docker-build-cache-github-actions) 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](https://github.com/runners-io/ci-measurements/tree/main/studies/D1-build-push-reference), 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.

```yaml
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](https://www.runners.io/blog/github-actions-cache-limit). 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.

```yaml
    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.

```yaml
    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.

```yaml
    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.

```yaml
    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.

```yaml
    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
```

```yaml
    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](https://www.runners.io/blog/docker-layer-cache-backends-measured), and the concepts, including layer order, are in [the Docker build cache post](https://www.runners.io/blog/docker-build-cache-github-actions).

## 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](https://www.runners.io/blog/github-actions-arm64-runners-private-repositories).

```yaml
    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](https://www.runners.io/docker-builds) and the [layer cache documentation](https://www.runners.io/docs/caching/docker-layer-cache) say what is kept between jobs without any `cache-to`.

## Sources

- [docker/build-push-action releases](https://github.com/docker/build-push-action/releases)
- [docker/build-push-action README (v7.4.0)](https://github.com/docker/build-push-action/blob/v7.4.0/README.md)
- [docker/build-push-action action.yml (v7.4.0)](https://github.com/docker/build-push-action/blob/v7.4.0/action.yml)
- [docker/setup-buildx-action releases](https://github.com/docker/setup-buildx-action/releases)
- [docker/setup-buildx-action action.yml (v4.4.1)](https://github.com/docker/setup-buildx-action/blob/v4.4.1/action.yml)
- [docker/setup-buildx-action README (v4.4.1)](https://github.com/docker/setup-buildx-action/blob/v4.4.1/README.md)
- [Cache storage backends (Docker)](https://docs.docker.com/build/cache/backends/)
- [GitHub Actions cache backend (Docker)](https://docs.docker.com/build/cache/backends/gha/)
- [Registry cache (Docker)](https://docs.docker.com/build/cache/backends/registry/)
- [Inline cache (Docker)](https://docs.docker.com/build/cache/backends/inline/)
- [Local cache (Docker)](https://docs.docker.com/build/cache/backends/local/)
- [Amazon S3 cache (Docker)](https://docs.docker.com/build/cache/backends/s3/)
- [Azure Blob Storage cache (Docker)](https://docs.docker.com/build/cache/backends/azblob/)
- [Cache management with GitHub Actions (Docker)](https://docs.docker.com/build/ci/github-actions/cache/)
- [Multi-platform builds (Docker)](https://docs.docker.com/build/building/multi-platform/)
- [Notification of upcoming breaking changes in GitHub Actions (GitHub changelog, 20 March 2025)](https://github.blog/changelog/2025-03-20-notification-of-upcoming-breaking-changes-in-github-actions/)
- [Read-only Actions cache for untrusted triggers (GitHub changelog, 26 June 2026)](https://github.blog/changelog/2026-06-26-read-only-actions-cache-for-untrusted-triggers/)
- [Publishing Docker images (GitHub)](https://docs.github.com/en/actions/tutorials/publish-packages/publish-docker-images)
- [Working with the Container registry (GitHub)](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
- [Secure use reference (GitHub)](https://docs.github.com/en/actions/reference/security/secure-use)
- [BuildKit README: Azure Blob Storage cache](https://github.com/moby/buildkit#azure-blob-storage-cache-experimental)
- [The workflows we ran (runners-io/ci-measurements, study D1)](https://github.com/runners-io/ci-measurements/tree/main/studies/D1-build-push-reference)

## 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.
