How to Cache on Ephemeral Runners With a Remote Cache

Ephemeral runners discard local disk, so caching must live in a remote store to survive between jobs.

Because an ephemeral runner is destroyed after one job, any on-disk cache vanishes. Point your caches at a remote backend: a self-hosted actions/cache server on S3, or a registry-backed BuildKit cache for images. Then a fresh runner still gets warm caches on its first job.

Steps

• For dependencies, run a self-hosted cache server (S3 backed) so actions/cache persists across ephemeral runners.
• For Docker layers, export cache to a registry with BuildKit cache-to/cache-from.
• Key caches on the lockfile hash so a fresh runner restores the right entry.

Registry-backed layer cache

- uses: docker/build-push-action@v6
  with:
    push: true
    tags: ghcr.io/my-org/app:latest
    cache-from: type=registry,ref=ghcr.io/my-org/app:buildcache
    cache-to: type=registry,ref=ghcr.io/my-org/app:buildcache,mode=max

Gotchas

• The default GitHub-hosted cache works from self-hosted runners too, but a local disk cache does not survive an ephemeral runner.
• A remote cache adds network transfer, so cache only what is expensive to rebuild.

Related guides