Cache management (original) (raw)

This page contains examples on using the cache storage backends with GitHub Actions.

Note

SeeCache storage backends for more details about cache storage backends.

In most cases you want to use theinline 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 theregistry cache example.

You can import/export cache from a cache manifest or (special) image configuration on the registry with theregistry cache exporter.

Cache backend API

Availability: Experimental

TheGitHub Actions cache exporterbackend uses theGitHub Cache service APIto 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) andtoken ($ACTIONS_RUNTIME_TOKEN) attributes only get populated in a workflow context.

Important

StartingApril 15th, 2025, only GitHub Cache service API v2 will be supported.

If you encounter the following error during your build:

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:

If you're building using the docker/build-push-action or docker/bake-actionactions 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:

If you're building using Docker Compose, you can use thedocker/setup-compose-action action:

If you're building using the Docker Engine with the containerd image store enabled, you can use the docker/setup-docker-action action:

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 byreproducible-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

Example CI action

For more information about this workaround, refer to theGitHub repository.

Local cache

Warning

At the moment, old cache entries aren't deleted, so the cache sizekeeps growing. The following example uses the Move cache step as a workaround (seemoby/buildkit#1896for more info).

You can also leverageGitHub cacheusing theactions/cache andlocal cache exporterwith this action: