Speed Up Docker Builds in GitHub Actions: A Cache Guide

FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
# Cache npm's download directory, not node_modules. This survives within a build
# even when the layer above is invalidated, so a lockfile change re-links from
# cache instead of re-downloading every tarball. Still `npm ci`, so the lockfile
# stays authoritative.
RUN --mount=type=cache,target=/root/.npm npm ci

The order does the first half of the work: package files, then npm ci, with the full source copied later in the builder stage. The cache mount points at npm's download folder, so when a lockfile change forces npm ci to re-run, packages already in the mount are not fetched again. On a cold runner that mount starts empty, which is why it is a bonus and not the plan.

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: |
            ${{ steps.meta.outputs.ref }}:latest
            ${{ steps.meta.outputs.ref }}:${{ github.sha }}
          cache-from: type=gha

The whole layer-cache setup is the last two lines. cache-from imports, cache-to exports, and mode=max is there because the deps and builder stages are not in the shipped image. The tags above it are unrelated to the cache: a cache hit changes how fast the image is built, never what is in it.

      - name: Restore Next.js build cache
        uses: actions/cache@v4
        with:
          path: .next/cache
          # SHA in the key so every run writes a fresh entry; restore-keys then
          # falls back to the most recent cache for the same lockfile, and
          # finally to any cache at all, rather than starting cold.
          key: next-cache-${{ hashFiles('package-lock.json') }}-${{ github.sha }}
          restore-keys: |
            next-cache-${{ hashFiles('package-lock.json') }}-
            next-cache-

A key that ends in the commit SHA is new on every run, so the post-job step always has something to save. restore-keys are prefixes tried in order: the newest cache for this exact lockfile wins, and any Next.js cache at all beats starting cold.

.next
!.next/cache

Two lines carry a lot. .next is excluded from the build context, then the negation brings back only .next/cache. Docker's rule is that the last matching line decides, so the exception must come after the exclusion it overrides.

          # The cache is restored, grown and saved again on every run, so
          # nothing ever shrinks it. Past the cap, save nothing: the next
          # build starts cold once, and the cache starts small again instead
          # of growing until the runner's disk runs out.
          size_mb="$(du -sm .next/cache | cut -f1)"
          if [ "$size_mb" -gt "$NEXT_CACHE_CAP_MB" ]; then
            echo "::warning title=Next.js cache over cap::.next/cache is ${size_mb} MB (cap ${NEXT_CACHE_CAP_MB} MB), so this run saves none and the next build starts cold."
            rm -rf .next/cache
          fi

The ceiling on the Next.js cache. Past the cap the step deletes the folder, so actions/cache skips the save with a warning and the next build starts cold once. A small, occasionally cold cache beats one that grows until the runner's disk fills.