Skip to content
Latchkey home
Documentation menu

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

  1. Replace the actions/cache step with two latchkey-dev/cache-action@v1 steps, one with action: restore and one with action: save; your path and key inputs carry over. restore-keys is not supported.
  2. One streaming request per save or restore, multi-threaded zstd compression, storage in the runner's region.
  3. Zero setup: storage and credentials are pre-provisioned on every Latchkey runner.
  4. A cache problem can slow a build down but never fails one; restore failures warn and continue.

Latchkey Fast Cache (latchkey-dev/cache-action@v1) 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.

fast cache · two runs of the same workflow

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.

FIG. 4.1-AThe first run after a lockfile change pays the full install plus the save; every run after it restores in seconds and skips the install. The times are this page's illustrative numbers.

Why it is fast#

  • Cache data moves in a single streaming HTTP request instead of the serial chunk pattern actions/cache@v4 uses: 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.

Illustrative time per run (s)
No cache180s
Cache hit~30s
Cache miss (new lockfile)~195s

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.

.github/workflows/ci.yml
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#

actions/cache@v4
  • Serial chunked transfers with per-chunk round trips
  • Works on any runner
  • Inputs: path, key, restore-keys
latchkey-dev/cache-action@v1
  • One streaming request per save or restore
  • Storage pre-provisioned, same region as the runner
  • path and key carry over, into a restore step and a save step; remove restore-keys, which the action does not accept

Safe defaults#

  • A restore failure never fails the job: you get a warning, cache-hit reads false, 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_dispatch or merge_group saves 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 by pull_request_target, workflow_run or issue_comment, restores from them, and each of its saves of a key it cannot restore ends with Cache save failed, continuing without saving while 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 lineWhat it tells you
Cache restored in {N}msThe restore completed, and how long it took
Cache saved in {N}msThe save completed, and how long it took
Cache missNo cache existed for the key; cache-hit is false and the job continues
Cache already exists for key=..., skipping saveThe save was skipped because an identical key is already stored
Cache save failed, continuing without savingThe 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/cache-action@v1 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.