Documentation menu
Dashboard & analytics
Managed runners
Team & notifications
Billing & plans
Workflow files
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
- One step:
latchkey-dev/wrapsdocker-cache-action@v1 docker buildx buildwith registry-backed layer caching. - Layers persist across Latchkey's single-use runners; only the layers your changes invalidate get rebuilt.
- Zero setup: the cache registry, credentials, and permissions are pre-provisioned per organization.
- 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#
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.
- FROM node:20-bookworm-slim AS buildcachedUnchanged, and nothing before it changed: reused from the cache.
- RUN apt-get update && apt-get install -y python3 make g++cachedUnchanged, and nothing before it changed: reused from the cache.
- WORKDIR /appcachedUnchanged, and nothing before it changed: reused from the cache.
- COPY package.json package-lock.json ./cachedUnchanged, and nothing before it changed: reused from the cache.
- RUN npm cicachedUnchanged, and nothing before it changed: reused from the cache.
- COPY . .rebuiltYou changed this line, so its layer is built again.
- RUN npm run buildrebuiltComes after line 6 in its stage, so it is built again.
- FROM node:20-bookworm-slimcachedPart of a separate stage on its own base image, and nothing it builds on changed: reused from the cache.
- WORKDIR /appcachedPart of a separate stage on its own base image, and nothing it builds on changed: reused from the cache.
- COPY --from=build /app/dist ./distrebuiltCopies the build stage's output, which line 6 changed.
- CMD ["node", "dist/server.js"]no layerSets the image's start command, which adds no layer.
Inputs and outputs#
| Input | Default | What it does |
|---|---|---|
tags | required | Tags for the built image |
context | . | Build context path |
dockerfile | Dockerfile | Path to the Dockerfile |
push | false | Push the built image |
build-args | none | Build arguments; values are masked in logs since they may contain secrets |
target | none | Target stage for multi-stage builds |
platforms | none | Target platforms for the build |
cache-mode | max | Cache scope: min or max (max caches all layers, including intermediate multi-stage layers) |
cache-tag | derived per image | Registry 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-to | none | Additional cache sources and destinations passed to the build |
| Output | What it tells you |
|---|---|
cache-configured | true 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-digest | Digest 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,
targetorplatformschange: the log shows anERROR: failed to configure registry cache importerline ending innot 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_dispatchormerge_groupbuilds 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/ 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.