Lorixen.
EN

Slow GitHub Actions builds? Cache your dependencies properly

Short answer: If every GitHub Actions run spends minutes downloading the same packages, add dependency caching. The simplest route is the built-in cache option in the setup action for your language, such as setup-node with cache: npm. For anything else, use actions/cache with a key based on a hash of your lockfile, plus restore-keys as a fallback. Then check your logs for cache hits, because a key that changes on every run, or a cache saved on a branch other runs can't read, quietly gives you no benefit.

How dependency caching works

GitHub's dependency caching stores a folder, such as your package manager's download cache, at the end of a successful job, and restores it at the start of later jobs. GitHub's reference explains the lookup order: the cache action first looks for an exact match to your key. If there isn't one, it tries partial matches, then each of your restore-keys in order. An exact match is a cache hit. Anything else is a cache miss, and on a miss the action creates a new cache with your key when the job completes successfully.

You can't change the contents of an existing cache. If your dependencies change, you need a new key, which is why keys are usually built from a hash of the lockfile.

The quick option: setup actions

For common package managers, GitHub's setup actions can manage the cache for you with minimal configuration. The reference lists setup-node for npm, Yarn and pnpm, setup-python for pip, pipenv and Poetry, setup-java for Gradle and Maven, setup-ruby for RubyGems, setup-go and setup-dotnet.

For a Node project, it's one extra line in the setup step:

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
- run: npm ci

This caches npm's download cache, using a hash of your lockfile as part of the key. npm ci still runs, but it installs from local files instead of the network. The setup-node README notes that recent major versions turn npm caching on automatically when package.json declares npm as its package manager, while Yarn and pnpm still need the cache input. Version numbers in these snippets are examples; check each action's README for the current major version.

The flexible option: actions/cache

When you need control over what's cached, or your tool isn't covered, use actions/cache directly:

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

The key changes whenever the lockfile changes. The restore key lets a run with a new lockfile start from the most recent older cache, so it only downloads what's different.

Why you keep getting cache misses

The key includes something that changes every run. Commit hashes, run numbers or timestamps in the key mean you never hit the same cache twice.

There's no lockfile, or it isn't committed. hashFiles returns a different result, or nothing useful, if the file it hashes isn't in the repository.

Branch scope. GitHub's reference explains that runs can restore caches created in the current branch or the default branch, usually main. A cache created on one feature branch isn't available to another feature branch. If main never runs the workflow, feature branches have nothing to fall back on. Running the workflow on pushes to main gives every branch a base cache.

The cache was evicted. GitHub removes cache entries that haven't been accessed in over 7 days. By default, each repository can hold 10 GB of caches in total; GitHub says usage beyond that is billed to your account, and once the limit is reached older caches are deleted by last access date. A repository with many branches and large caches can churn through that quickly.

The job failed. New caches are saved when the job completes successfully, so a failing build never saves one.

What to cache, and what not to

  • Cache download caches, such as ~/.npm or pip's cache directory, rather than node_modules. Download caches are safe across small changes; a cached node_modules can hide problems when the lockfile changes.
  • Cache build tool caches where your framework has one, for example a compiler or bundler cache folder, with a key that reflects the inputs.
  • Never cache secrets. GitHub recommends not storing sensitive information such as access tokens or login credentials in cached paths. Anyone with read access can open a pull request and access the contents of a cache, and pull requests from forks can read caches on the base branch.
  • Keep matrix builds separate. Include the operating system and language version in the key when you test on several, so caches don't clash.

Measure the difference

Before changing anything, note how long the install step takes in a few recent runs. After adding caching, look at the "Post" step of the cache action and the install step's duration. You should see "Cache restored" messages and a shorter install. If not, compare the key in two consecutive runs; the part that differs is your problem.

Beyond package caches

If your workflow builds Docker images, the package cache won't help much. Docker's own layer caching, and ordering your Dockerfile so dependency installs come before copying source code, makes the bigger difference. If tests are the slow part, splitting them across parallel jobs helps more than any cache.

A worked example

An illustrative Wellington web agency had a workflow that took several minutes per push, most of it npm install downloading packages. Their first caching attempt used the commit SHA in the key, so every run missed. They switched to setup-node with cache: npm, replaced npm install with npm ci, and added the workflow to pushes on main so feature branches had a cache to restore. Install time dropped noticeably, and the logs showed cache hits on most runs.

FAQ

Does caching cost anything?

Caches up to the repository's default limit are included; GitHub's documentation says usage beyond 10 GB is billed. Check your plan before raising limits.

Can I clear a bad cache?

Yes. Caches can be listed and deleted from the repository's Actions settings, or you can change the key prefix to start fresh.

Should I cache node_modules?

Generally no. Cache the package manager's download cache and let npm ci build node_modules cleanly.

Why does the first run on a new branch miss?

It looks for a cache on the branch, then on the default branch. If neither has one with a matching key, it misses once and saves a new one.

If your CI runs are slow or flaky, send us a recent workflow file and we'll suggest where caching and parallel jobs would help.

Sources

WhatsAppBook a call