Documentation menu
Dashboard & analytics
Managed runners
Team & notifications
Billing & plans
Workflow files
Dependency caching (Fast Cache)
Latchkey Fast Cache saves and restores dependency caches in a single streaming request, with storage in the same region as your runner and zero configuration.
In short
- Replace the
actions/cachestep with twolatchkey-dev/steps, one withcache-action@v1 action: restoreand one withaction: save; yourpathandkeyinputs carry over.restore-keysis not supported. - One streaming request per save or restore, multi-threaded zstd compression, storage in the runner's region.
- Zero setup: storage and credentials are pre-provisioned on every Latchkey runner.
- A cache problem can slow a build down but never fails one; restore failures warn and continue.
Latchkey Fast Cache (latchkey-dev/) is a lightweight GitHub Action for saving and restoring dependency caches (node_modules, package registries, build artifacts) on Latchkey managed runners. Repeat runs skip installs your pipeline has already done. This is a GitHub action for Latchkey on GH. On Latchkey CI, use the latchkey/cache-restore and latchkey/cache-save steps instead.
Two runs of the same workflow. Run 1, after a lockfile change: Restore dependencies logs Restoring cache: key=deps-Linux-4c1d… version=Linux and Cache miss, Install dependencies runs npm ci for 3 minutes, and Save dependencies logs Saving cache, the node_modules path and Cache saved in 2140ms; the run takes 3m 15s, and the entry now sits in the cache beside the runners. Run 2, same lockfile: Restore dependencies logs Cache restored in 1830ms, Install dependencies is skipped, and Save dependencies logs Cache already exists for key=deps-Linux-4c1d…, skipping save; the run takes 30s.
Why it is fast#
- Cache data moves in a single streaming HTTP request instead of the serial chunk pattern
actions/cache@v4uses: no per-chunk round trips, no temp files. - Compression and decompression are multi-threaded (zstd), and uploads and downloads run as parallel transfers.
- Storage lives in the same region as your runner, so the bytes never travel far.
- Every save and restore prints its timing in the job log, so you can measure the difference on your own builds.
What caching is worth: a worked example#
The numbers below are illustrative, not a measured benchmark: they show the shape of the win, and your own builds will differ. Picture a Node.js app on latchkey-medium with a ~400 MB node_modules. Without caching, npm ci resolves and downloads everything on every run: call it ~3 minutes (180 s). With a cache hit, the restore is a single streaming download decompressed on the fly, landing in seconds (say ~10 s), and if you skip the install step on a hit (the workflow example below does exactly that) the 3-minute install disappears; teams that run npm ci anyway see it finish in tens of seconds against the warm node_modules. Call the hit path ~30 s of dependency work instead of 180.
On those assumptions that is roughly 2.5 minutes saved per run, and at 100 runs a week it works out to about 250 runner-minutes a week, a little over four hours. Caching does not help every run: a cold key after a lockfile change still pays the full install plus the save (~195 s here), slightly worse than no cache at all; the payoff is every hit that follows.
Add it to a workflow#
Add two steps: one with action: restore and one with action: save. Each takes a key and one or more path entries (newline or space separated; ~ is supported). The restore step exposes a cache-hit output so you can skip install steps when the cache lands.
jobs: build: runs-on: latchkey-medium steps: - uses: actions/checkout@v4 - name: Restore dependencies id: cache uses: latchkey-dev/cache-action@v1 with: action: restore key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }} path: node_modules - name: Install dependencies if: steps.cache.outputs.cache-hit != 'true' run: npm ci - name: Save dependencies uses: latchkey-dev/cache-action@v1 with: action: save key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }} path: node_modules
Switching from actions/cache#
- Serial chunked transfers with per-chunk round trips
- Works on any runner
- Inputs: path, key, restore-keys
- One streaming request per save or restore
- Storage pre-provisioned, same region as the runner
pathandkeycarry over, into a restore step and a save step; removerestore-keys, which the action does not accept
Safe defaults#
- A restore failure never fails the job: you get a warning,
cache-hitreadsfalse, and the run continues. - Save is skipped automatically when the key already exists, so identical caches are never re-uploaded.
- Caches are isolated per organization and automatically versioned by operating system; encode finer isolation (like OS versions) in your cache key.
- Cache entries are stored server-side with a 14-day retention, so stale caches age out on their own.
- On GitHub Actions, only a job of a run started by
push,pull_request,schedule,workflow_dispatchormerge_groupsaves to your caches, and never one of a pull request from a fork or of a run Dependabot started or re-ran. A job of any other run, such as one started bypull_request_target,workflow_runorissue_comment, restores from them, and each of its saves of a key it cannot restore ends withCache save failed, continuing without savingwhile the job goes on. When you merge a Dependabot pull request yourself, the run your merge starts saves, as the run of any other push does.
What you see in job logs#
| Log line | What it tells you |
|---|---|
Cache restored in {N}ms | The restore completed, and how long it took |
Cache saved in {N}ms | The save completed, and how long it took |
Cache miss | No cache existed for the key; cache-hit is false and the job continues |
Cache already exists for key=..., skipping save | The save was skipped because an identical key is already stored |
Cache save failed, continuing without saving | The save did not land, and the job went on without it. A job of a pull request from a fork, of a run Dependabot started or re-ran, or of a run started by an event other than push, pull_request, schedule, workflow_dispatch or merge_group, never saves to your caches, so each of its saves of a key it cannot restore ends this way |
Caching you do not have to find#
The AI Scan detects which caches your project needs and lists them in the proposed runner configuration, and the Migrate Runners tool can inject cache steps as it moves workflows over. Teams that never hand-tune caching still get it.
For the broader craft - trimming install time, splitting slow suites, parallelizing - the Learn library has a hands-on CI optimization hub with guides you can apply on any runner.
Q.01How do I switch from actions/cache to Fast Cache?
Replace the actions/cache step with two latchkey-dev/ steps: one with action: restore where the old step was, and one with action: save after the steps that build what you cache, each with your path and key inputs. Remove any restore-keys input: the action restores only an entry whose key matches exactly and has no prefix fallback, so the first run after a key change, such as a lockfile change, is a cache miss that saves a new entry.
Q.02What makes Fast Cache faster than actions/cache?
One streaming request per save or restore instead of a multi-step upload, multi-threaded zstd compression, and cache storage in the same region as the runner. The saving is in transfer and decompression, which is where most of the wall-clock in a cache step actually goes.
Q.03What happens if the cache fails?
The build continues. A restore failure warns in the log and the step proceeds to a normal install, so a cache problem can slow a build down but never fails one. That is deliberate: a cache is an optimisation, and an optimisation that can break a pipeline is a liability.