Skip to content
Latchkey home
Documentation menu

Docker layer caching

Latchkey Docker Cache Build wraps docker buildx with registry-backed layer caching, so repeat image builds reuse every unchanged layer across ephemeral runners.

In short

  1. One step: latchkey-dev/docker-cache-action@v1 wraps docker buildx build with registry-backed layer caching.
  2. Layers persist across Latchkey's single-use runners; only the layers your changes invalidate get rebuilt.
  3. Zero setup: the cache registry, credentials, and permissions are pre-provisioned per organization.
  4. Portable: on non-Latchkey runners the same step detects no registry and builds normally, without cache flags.

Every Latchkey runner is a fresh, isolated instance. That is good for security and bad for Docker's local layer cache, which disappears with the runner. Latchkey Docker Cache Build solves it with a layer cache stored in a private container registry managed by Latchkey for your organization: matching layers from earlier builds are reused, and the updated cache is written back for the next run.

Add it to your workflow#

.github/workflows/build.yml
jobs:
  build:
    runs-on: latchkey-medium
    steps:
      - uses: actions/checkout@v4
      - uses: latchkey-dev/docker-cache-action@v1
        with:
          context: .
          tags: myapp:latest
          push: true

That is the whole integration: you supply the inputs you would give any Docker build, and Latchkey handles the registry, the credentials, and the cache wiring. By default the action uses cache-mode: max, which caches all layers including intermediate layers from multi-stage builds. Single-platform builds with push: false load the built image into the runner's local Docker daemon.

What layer caching is worth: a worked example#

Illustrative numbers, not a measured benchmark. Take a multi-stage Node.js image that builds in ~8 minutes uncached: base image, system packages, dependency install, compile, assemble. With the layer cache in place, a source-only change invalidates just the final layers; everything above them is pulled from the registry cache, and the rebuild lands in the 1 to 2 minute range. A commit that touches the dependency stage invalidates more layers and rebuilds more, so the win scales with how much of your Dockerfile a typical change leaves untouched. The default cache-mode: max trades a bigger cache push after the build for better hit rates on exactly these multi-stage rebuilds, since intermediate stage layers are cached too.

Illustrative build time (min)
No layer cache~8 min
Layer cache, source-only change~1-2 min
Change one line, see which layers rebuild
Layer cache
OnOff
Dockerfile
  1. FROM node:20-bookworm-slim AS build
    cachedUnchanged, and nothing before it changed: reused from the cache.
  2. RUN apt-get update && apt-get install -y python3 make g++
    cachedUnchanged, and nothing before it changed: reused from the cache.
  3. WORKDIR /app
    cachedUnchanged, and nothing before it changed: reused from the cache.
  4. COPY package.json package-lock.json ./
    cachedUnchanged, and nothing before it changed: reused from the cache.
  5. RUN npm ci
    cachedUnchanged, and nothing before it changed: reused from the cache.
  6. COPY . .
    rebuiltYou changed this line, so its layer is built again.
  7. RUN npm run build
    rebuiltComes after line 6 in its stage, so it is built again.
  8. FROM node:20-bookworm-slim
    cachedPart of a separate stage on its own base image, and nothing it builds on changed: reused from the cache.
  9. WORKDIR /app
    cachedPart of a separate stage on its own base image, and nothing it builds on changed: reused from the cache.
  10. COPY --from=build /app/dist ./dist
    rebuiltCopies the build stage's output, which line 6 changed.
  11. CMD ["node", "dist/server.js"]
    no layerSets the image's start command, which adds no layer.
Line 6 changed: 3 layers rebuild, 7 come from the cache.
With the cache on, a runner pulls the layers your change did not invalidate from the private registry Latchkey manages for your organization, and the updated cache is written back for the next run. The default cache-mode: max caches the build stage's layers too. Docker reuses a layer only while it and every layer before it in its stage are unchanged; a COPY --from layer is keyed on the files it copies.

Inputs and outputs#

InputDefaultWhat it does
tagsrequiredTags for the built image
context.Build context path
dockerfileDockerfilePath to the Dockerfile
pushfalsePush the built image
build-argsnoneBuild arguments; values are masked in logs since they may contain secrets
targetnoneTarget stage for multi-stage builds
platformsnoneTarget platforms for the build
cache-modemaxCache scope: min or max (max caches all layers, including intermediate multi-stage layers)
cache-tagderived per imageRegistry tag that holds one image's layer cache. Unset, one is derived for each image from the repository, the Dockerfile path, target and platforms; set your own when builds of one Dockerfile differ only in their build arguments
extra-cache-from / extra-cache-tononeAdditional cache sources and destinations passed to the build
OutputWhat it tells you
cache-configuredtrue when registry layer caching was set up for the build, false otherwise; a job that builds without the layer cache, such as one of a pull request from a fork or of a run Dependabot started or re-ran, still reads true
image-digestDigest of the built image

Safe on any runner#

  • On non-Latchkey runners (for example GitHub-hosted), the action detects the cache registry is not available and builds normally, without cache flags. One workflow file stays portable across runner types.
  • On a tag's first build the cache is empty, and a derived tag is new whenever the repository, the Dockerfile path, target or platforms change: the log shows an ERROR: failed to configure registry cache importer line ending in not found, and the build continues. If a cached build fails, the action automatically retries without cache. First runs never break because of caching.
  • Build-arg values are masked in logs, so secrets passed as build args do not leak into job output.
  • Caches are isolated per organization.
  • On GitHub Actions, a job of a run started by any event other than push, pull_request, schedule, workflow_dispatch or merge_group builds without the layer cache, as a job of a pull request from a fork or of a run Dependabot started or re-ran does, and the refused cache neither fails the build nor runs it twice.
Q.01How does Docker layer caching work on ephemeral runners?

latchkey-dev/docker-cache-action@v1 wraps docker buildx build with a registry-backed layer cache, so layers persist in a registry rather than on the machine. Each single-use runner pulls the layers your change did not invalidate and rebuilds only the ones it did.

Q.02Do I have to configure a registry or credentials?

No. The cache registry, its credentials and the permissions are pre-provisioned per organization, so the step works with no setup. There is nothing to create and no secret to add.

Q.03Does the action still work on non-Latchkey runners?

Yes. On a runner with no Latchkey cache registry available the step detects that and runs a normal docker buildx build without cache flags, so a workflow shared across runner types does not need branching.