Cache management with GitHub Actions
This page contains examples on using the cache storage backends with GitHub Actions.
Note
See Cache storage backends for more details about cache storage backends.
Inline cache
In most cases you want to use the
inline cache exporter.
However, note that the inline
cache exporter only supports min
cache mode.
To use max
cache mode, push the image and the cache separately using the
registry cache exporter with the cache-to
option, as shown in the
registry cache example.
name: ci
on:
push:
branches:
- "main"
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: user/app:latest
cache-from: type=registry,ref=user/app:latest
cache-to: type=inline
Registry cache
You can import/export cache from a cache manifest or (special) image configuration on the registry with the registry cache exporter.
name: ci
on:
push:
branches:
- "main"
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: user/app:latest
cache-from: type=registry,ref=user/app:buildcache
cache-to: type=registry,ref=user/app:buildcache,mode=max
GitHub cache
Cache backend API
Experimental
This cache exporter is experimental. Please provide feedback on BuildKit repositoryopen_in_new if you experience any issues.
The
GitHub Actions cache exporter
backend uses the
GitHub Cache APIopen_in_new
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_CACHE_URL
) and
token
($ACTIONS_RUNTIME_TOKEN
) attributes only get populated in a workflow
context.
name: ci
on:
push:
branches:
- "main"
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: user/app:latest
cache-from: type=gha
cache-to: type=gha,mode=max
Cache mounts
BuildKit doesn't preserve cache mounts in the GitHub Actions cache by default.
If you wish 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
open_in_new.
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.
name: ci
on: push
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Docker meta
id: meta
uses: docker/metadata-action@v5
with:
images: YOUR_IMAGE
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@v3
with:
path: go-build-cache
key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }}
- name: inject go-build-cache into docker
# v1 was composed of two actions: "inject" and "extract".
# v2 is unified to a single action.
uses: reproducible-containers/buildkit-cache-dance@v2.1.2
with:
cache-source: go-build-cache
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
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 repositoryopen_in_new.
Local cache
Warning
At the moment, old cache entries aren't deleted, so the cache size keeps growingopen_in_new. The following example uses the
Move cache
step as a workaround (seemoby/buildkit#1896
open_in_new for more info).
You can also leverage GitHub cacheopen_in_new using the actions/cacheopen_in_new and local cache exporter with this action:
name: ci
on:
push:
branches:
- "main"
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Cache Docker layers
uses: actions/cache@v3
with:
path: /tmp/.buildx-cache
key: ${{ runner.os }}-buildx-${{ github.sha }}
restore-keys: |
${{ runner.os }}-buildx-
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: user/app:latest
cache-from: type=local,src=/tmp/.buildx-cache
cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
- # Temp fix
# https://github.com/docker/build-push-action/issues/252
# https://github.com/moby/buildkit/issues/1896
name: Move cache
run: |
rm -rf /tmp/.buildx-cache
mv /tmp/.buildx-cache-new /tmp/.buildx-cache