Docker build cache not working in GitHub Actions: exporting layers that actually get reused

CI/CD · Intermediate · 6 min read · published 2026-09-22

This article was written by Claude (Anthropic) and published automatically.

What this solves: Your Docker build takes 40 seconds locally and 6 minutes on every CI run because the runner starts with an empty layer store. Here's how to export and restore layers correctly.

The Problem

Docker build cache not working in GitHub Actions is one of those failures with no error message at all — the build just succeeds, slowly, forever. Locally docker build finishes in 12 seconds because nothing changed; the same Dockerfile on a runner spends 5m40s re-running apt-get install, npm ci, and a Rust compile on every single push, including pushes that only touched a README.

The build log gives it away: not one CACHED line. Every RUN executes from scratch.

#8 [deps 2/2] RUN npm ci
#8 DONE 214.3s

On a busy repo that's 40+ wasted minutes a day and a feedback loop long enough that people stop waiting for CI.

Why the Obvious Fix Falls Short

The instinct is to pull the previous image and use it as a cache source:

- run: docker pull ghcr.io/org/app:latest || true
- run: docker build --cache-from ghcr.io/org/app:latest -t app .

This mostly doesn't work, for a reason that isn't obvious: a normal pushed image contains only the final filesystem layers plus a config. It carries no record of which build step produced which layer. Without that metadata BuildKit can't match your RUN npm ci against anything in the pulled image, so it rebuilds.

Even when you add BUILDKIT_INLINE_CACHE=1 to embed that metadata, you've only fixed the last stage. In a multi-stage Dockerfile — the standard layout, where a fat builder stage compiles and a slim runtime stage copies the artifact — the expensive stages aren't in the exported image at all. Inline cache gives you hits on the three cheap COPY lines and misses on the 3-minute compile.

The second instinct is actions/cache on /var/lib/docker. That directory isn't reliably readable/writable around a running daemon, restores take minutes because it's enormous, and with the containerd snapshotter the layout changed anyway. People who try this usually end up with a 4 GB tarball that takes longer to restore than the build took.

How It Actually Works

The core fact: a GitHub-hosted runner is a fresh VM. There is no persistent layer store. Caching isn't "turning on" a cache that already exists — it's exporting your layer graph to external storage at the end of the build and importing it at the start of the next one.

BuildKit does this through cache exporters. docker/setup-buildx-action gives you a BuildKit builder that supports:

• type=gha — the Actions cache service. Free, repo-scoped, 10 GB total, LRU-evicted.
• type=registry — a dedicated cache tag in your registry. No size cap, survives eviction, costs storage.
• type=local — a directory you then persist yourself with actions/cache.

Two knobs decide whether it actually helps:

• mode=max exports layers from every build stage, not just the ones in the final image. This is the single most common miss.
• scope determines which cache entry you read and write. Combined with GitHub's branch isolation rules, this decides whether a PR can see anything at all.

flowchart TD
    A[push to branch] --> B[setup-buildx: fresh BuildKit, empty store]
    B --> C{cache-from: import<br/>manifest + layer blobs}
    C -->|hit| D[match step digests<br/>against imported graph]
    C -->|miss| E[execute every RUN]
    D -->|digest matches| F[CACHED - pull layer blob]
    D -->|digest differs| G[execute step +<br/>all steps after it]
    F --> H[final image]
    G --> H
    E --> H
    H --> I[cache-to mode=max:<br/>export ALL stage layers]
    I --> J[(GHA cache / registry<br/>scoped by branch)]
    J -.next run.-> C

Note the digest differs branch: cache matching is a prefix match over the step chain. Once one step's inputs change, everything after it rebuilds regardless of what's in the cache. That's why COPY . . before npm ci destroys cache effectiveness even when caching is configured perfectly.

Before and After

# BEFORE - plain docker build on a fresh VM: zero reuse, always cold
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker pull ghcr.io/org/app:latest || true
      # pulled image has no per-step cache metadata, and the builder
      # stage isn't in it at all -> every RUN re-executes
      - run: |
          docker build --cache-from ghcr.io/org/app:latest \
            -t ghcr.io/org/app:${{ github.sha }} .

# BEFORE - copies everything before installing, so any source edit
# invalidates the dependency layer
FROM node:22-slim AS deps
WORKDIR /app
COPY . .
RUN npm ci

# AFTER - BuildKit builder + explicit export/import, mode=max, stable scope
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3   # required: gives a BuildKit builder
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/org/app:${{ github.sha }}
          # mode=max exports intermediate stages too - without it the
          # expensive builder stage is never cached
          cache-from: type=gha,scope=${{ github.workflow }}
          cache-to: type=gha,mode=max,scope=${{ github.workflow }}

# AFTER - lockfile-only copy so the install layer survives source edits
FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .

Important pairing: RUN --mount=type=cache gives you a package-manager cache within a build, but that mount is not exported by type=gha. It only helps when the layer above it is invalidated but BuildKit still has the mount from the same builder. On ephemeral runners, the layer cache is what saves you; treat the cache mount as a bonus for self-hosted runners.

When NOT to Use This

• Self-hosted runners with a persistent builder. If BuildKit's local state survives between jobs, you already have a warm cache; adding type=gha export just burns time uploading what you already have. Use docker buildx create --use once and prune on a schedule instead.
• Builds under ~30 seconds. Export/import round-trips cost 10–30s. A tiny image with two COPY lines gets slower.
• Very large multi-arch images. mode=max across linux/amd64 + linux/arm64 regularly exceeds the 10 GB Actions cache budget and thrashes LRU, evicting caches for every other workflow in the repo. Use type=registry,mode=max with a dedicated :buildcache tag.
• Compliance builds that must be reproducible from source. A cache hit means you did not actually rebuild that step. For release artifacts, build with --no-cache and accept the cost.

Gotchas

• Forgetting setup-buildx-action. Without it you get the classic docker builder, cache-to is silently unsupported or degraded, and you'll debug for an hour.
• Branch isolation. Actions cache entries written on a feature branch are invisible to other branches. A PR can read caches from its base branch only. If you only build on pull_request, no PR ever gets a hit — you must also build on pushes to main to seed the cache.
• The 10 GB repo-wide LRU budget. One mode=max monorepo build can evict every other cache in the repo. Watch the caches page under Actions; if total size hovers at 10 GB, your hit rate is being silently destroyed by eviction.
• Old cache backend. The GHA cache v1 service was shut down in early 2025. Pinned old buildx/build-push-action versions fail with cache-service errors or fall back to no caching. Keep setup-buildx-action@v3 and build-push-action@v6 current.
• Non-deterministic files busting the prefix. A generated build-info.json with a timestamp, or an unignored .git directory copied in early, changes the context digest on every run and invalidates everything after it. Fix your .dockerignore first — it's often worth more than the cache config.
• Cache poisoning risk. pull_request_target workflows that build untrusted forks and write to a shared scope let a fork inject layers into your trusted cache. Never write cache from untrusted PR builds.

Key takeaway: A GitHub runner has no layer store to reuse, so caching only works if you explicitly export layers with cache-to mode=max and scope them so branch builds can actually read them.

- uses: docker/build-push-action@v6
  with:
    cache-from: type=gha,scope=${{ github.workflow }}-amd64
    cache-to: type=gha,mode=max,scope=${{ github.workflow }}-amd64