Text of docs.docker.com › build › ci › github-actions › cache as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Cache management with GitHub Actions | Docker Docs

Skip to content Search or ask Docker Search documentation Ask Docker Start a new chat Answers are generated based on the documentation. On this page: Docker Build Use Docker GitHub Builder with the GitHub Actions cache backend for reusable build workflows. The individual-action examples cover other cache backends and cache mounts. Note See Cache storage backends for more details about cache storage backends. GitHub cache Enable cache with GitHub Builder Docker GitHub Builder disables caching by default.

Set cache: true to import and export GitHub Actions cache. Set cache-mode: max to export intermediate layers, and use cache-scope to separate builds for different images. GitHub Builder adds the platform to the scope for distributed builds and makes cache export failures non-fatal. name : ci on : push : jobs : build : uses : docker/github-builder/.github/workflows/build.yml@v1 permissions : contents : read id-token : write with : output : image push : true cache : true cache-mode : max cache-scope : app meta-images : user/app secrets : registry-auths : | - registry: docker.io username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} The same cache inputs are available with the Bake workflow .

See cache write restrictions for event restrictions. GitHub Builder's cache-mode input selects the layers to export ( min or max ); it doesn't grant cache write access. Cache backend API The following examples configure the backend with individual actions. Availability: Experimental The GitHub Actions cache exporter backend uses the GitHub Cache service API to fetch and upload cache blobs. That's why you should only use this cache backend in a GitHub Action workflow, as the url ( $ACTIONS_RESULTS_URL ) and token ( $ACTIONS_RUNTIME_TOKEN ) attributes only get populated in a workflow context. name : ci on : push : jobs : docker : runs-on : ubuntu-latest steps : - name : Login to Docker Hub uses : docker/login-action@v4 with : username : ${{ vars.DOCKERHUB_USERNAME }} password : ${{ secrets.DOCKERHUB_TOKEN }} - name : Set up Docker Buildx uses : docker/setup-buildx-action@v4 - name : Build and push uses : docker/build-push-action@v7 with : push : true tags : user/app:latest cache-from : type=gha cache-to : type=gha,mode=max Important As of April 15th, 2025, only GitHub Cache service API v2 is supported. .

The legacy v1 API has been shut down. If you encounter the following error during your build: ERROR: failed to solve: This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset You're probably using outdated tools that only support the legacy GitHub Cache service API v1. Here are the minimum versions you need to upgrade to depending on your use case: Docker Buildx >= v0.21.0 BuildKit >= v0.20.0 Docker Compose >= v2.33.1 Docker Engine >= v28.0.0 (if you're building using the Docker driver with containerd image store enabled) If you're building using the docker/build-push-action or docker/bake-action actions on GitHub hosted runners, Docker Buildx and BuildKit are already up to date but on self-hosted runners, you may need to update them yourself.

Alternatively, you can use the docker/setup-buildx-action action to install the latest version of Docker Buildx: - name : Set up Docker Buildx uses : docker/setup-buildx-action@v4 with : version : latest If you're building using Docker Compose, you can use the docker/setup-compose-action action: - name : Set up Docker Compose uses : docker/setup-compose-action@v2 with : version : latest If you're building using the Docker Engine with the containerd image store enabled, you can use the docker/setup-docker-action action: - name : Set up Docker uses : docker/setup-docker-action@v5 with : version : latest daemon-config : | { "features": { "containerd-snapshotter": true } } Cache write restrictions Cache export requires write access to the GitHub Actions cache.

GitHub gives events such as issue_comment and pull_request_target read-only cache access by default when they run in the default-branch context. These workflows can restore existing cache entries, but exporting with cache-to: type=gha can fail with error writing layer blob: failed to reserve cache , even after the image has been built and pushed. This also affects pull_request workflows with types: [closed] when a pull request is merged into the default branch: the run uses the target branch ref instead of the pull request merge ref.

Regular pull_request runs using a merge ref retain read-write cache access by default. See GitHub's cache access policy . For workflows with read-only cache access, keep cache-from: type=gha and omit cache-to . Populate the cache from a workflow with write access, such as a push workflow on the default branch. For builds after a merge, use push on the target branch instead of pull_request with types: [closed] . GitHub's workflow or job-level cache-mode setting can override the default cache access.

Granting write access to untrusted workflows increases the risk of cache poisoning. If cache export is optional, you can make export failures non-fatal: cache-from : type=gha cache-to : type=gha,mode=max,ignore-error=true ignore-error=true suppresses all cache export errors, not only access errors. It doesn't grant write access or save the cache when writes are denied. Cache mounts BuildKit doesn't preserve cache mounts in the GitHub Actions cache by default.

To put your cache mounts into GitHub Actions cache and reuse it between builds, you can use a workaround provided by reproducible-containers/buildkit-cache-dance . This GitHub Action creates temporary containers to extract and inject the cache mount data with your Docker build steps. The following example shows how to use this workaround with a Go project. Example Dockerfile in build/package/Dockerfile FROM golang:1.21.1-alpine as base-build WORKDIR /build RUN --mount = type = cache,target = /go/pkg/mod \ --mount = type = bind,source = go.mod,target = go.mod \ --mount = type = bind,source = go.sum,target = go.sum \ go mod download RUN --mount = type = cache,target = /go/pkg/mod \ --mount = type = cache,target = /root/.cache/go-build \ --mount = type = bind,target = . \ go build -o /bin/app ./src ...

Example CI action name : ci on : push : jobs : build : runs-on : ubuntu-latest steps : - name : Login to Docker Hub uses : docker/login-action@v4 with : username : ${{ vars.DOCKERHUB_USERNAME }} password : ${{ secrets.DOCKERHUB_TOKEN }} - name : Set up QEMU uses : docker/setup-qemu-action@v4 - name : Set up Docker Buildx uses : docker/setup-buildx-action@v4 - name : Docker meta id : meta uses : docker/metadata-action@v6 with : images : user/app tags : | type=ref,event=branch type=ref,event=pr type=semver,pattern={{version}} type=semver,pattern={{major}}.{{minor}} - name : Go Build Cache for Docker uses : actions/cache@v5 with : path : go-build-cache key : ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }} - name : Inject go-build-cache uses : reproducible-containers/buildkit-cache-dance@4b2444fec0c0fb9dbf175a96c094720a692ef810 # v2.1.4 with : cache-source : go-build-cache - name : Build and push uses : docker/build-push-action@v7 with : cache-from : type=gha cache-to : type=gha,mode=max file : build/package/Dockerfile push : ${{ github.event_name != 'pull_request' }} tags : ${{ steps.meta.outputs.tags }} labels : ${{ steps.meta.outputs.labels }} platforms : linux/amd64,linux/arm64 For more information about this workaround, refer to the GitHub repository .

Local cache Note Exporting to a directory that already holds a cache leaves the blobs of the previous export behind, so the directory grows with every run. The following example passes reset=true to delete them. This parameter requires Buildx version 0.35.0 or later. You can also leverage GitHub cache using the actions/cache and local cache exporter with this action: name : ci on : push : jobs : docker : runs-on : ubuntu

The rest of this page is on the live site.