# GitHub Actions cache

The GitHub Actions cache keeps files between workflow runs, such as downloaded packages or build output, so a job can restore them instead of making them again. You use it through `actions/cache` or the `cache` option of a `setup-*` action.

## How it works

A cache step names a path, a key and, if you like, fallback keys:

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

1. **Exact hit.** If an entry has the same `key`, it is restored and nothing is saved at the end.
2. **Partial hit.** Otherwise the `restore-keys` are tried in order as prefixes, and the newest match is restored.
3. **Save.** When the key missed, the path is packed and uploaded under the key after the job succeeds.

Put a hash of the lockfile in the key, so the cache changes when the dependencies do. The `setup-*` actions do this for you:

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

## Which branches can read a cache

A run can restore caches made on its own branch and on the default branch. Sibling branches cannot read each other's caches, so the first run on a new branch reads from the default branch.

## Limits

| Limit | GitHub |
| --- | --- |
| Included storage | 10 GB per repository |
| Above that | $0.07 per GB-month, if an admin raises the limit |
| Unused entries | Removed after 7 days without a read |
| Over the limit | Least recently used entries go first |
| Rate | 200 uploads and 1,500 downloads a minute per repository |

## Where the time goes

Every restore downloads the archive and unpacks it; every save packs and uploads one. For a large cache that can take longer than the work it saves. Cache what is slow to make and small to store:

- Package downloads: `~/.npm`, `~/.cache/pip`, `~/.cargo/registry`, `~/.m2`.
- Compiler and build caches: ccache, Gradle, Turborepo, Next.js.
- Docker layers: `cache-from: type=gha` in `docker/build-push-action`.

Avoid caching `node_modules` across lockfile changes, and avoid one huge key: split by tool so a change in one does not throw away the rest.

## The cache on Groundbox runners

On Groundbox the same cache steps work with no change. The runner sends its cache calls to a cache server on the machine the job runs on, so a restore reads from local disk instead of the internet. Entries are kept per team, repository and branch. The machine also has mirrors for npm, PyPI, crates, apt and Docker Hub, and a Docker layer cache that a stock `docker build` uses.

In our benchmark, fmtlib/fmt's warm run restores a compiler cache. Its median job time was 7 s on `groundbox-2vcpu` and 29 s on GitHub's `ubuntu-latest` (5 runs each). See [the benchmark](https://groundbox.dev/benchmark).

## Questions

### How big can the GitHub Actions cache be?

10 GB per repository is included. Admins can set a higher limit, and storage past the included amount is billed at $0.07 per GB-month.

### How long does GitHub keep a cache?

An entry that has not been read in 7 days is removed. Over the size limit, the least recently used entries go first.

### Can a branch use another branch's cache?

A run can restore caches from its own branch and from the default branch. Sibling branches cannot read each other's caches.

### Why is my cache restore slow?

The archive is downloaded on every run. A large cache spends time on the network and on unpacking; caching less, or keeping the cache near the runner, helps.

### Does Groundbox need a different cache action?

No. actions/cache and the setup-* cache options work as they are; on Groundbox their cache is served from the machine the job runs on.

## Sources

Checked on 2026-11-19, on each company's own pages. Prices change; their pages are the final word.

- [GitHub: Dependency caching](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching)
- [GitHub: Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions)

## Related

- [GitHub Actions runners](https://groundbox.dev/github-actions-runners): What a GitHub Actions runner is, the four kinds you can use, what each costs per minute, and measured job times on GitHub-hosted and Groundbox runners.
- [GitHub Actions cost](https://groundbox.dev/github-actions-cost): How GitHub bills Actions minutes: per-minute prices by runner, included usage per plan, rounding to the minute, and worked monthly examples.
- [Build cache](https://groundbox.dev/build-cache): A remote build cache for five build tools, shared by CI jobs, sandboxes, laptops and agents. Set up on Groundbox runners already, one store per team, included.
- [CI in one line](https://groundbox.dev/docs/ci): Move a GitHub Actions workflow to Groundbox: runner labels and sizes, caches, groundbox migrate and groundbox ci wait.
- [CI runners](https://groundbox.dev/ci-runners): Change runs-on to switch. 2 / 4 / 8 / 16 vCPU at $0.003 / $0.006 / $0.011 / $0.021 a minute, billed by the second, with caches and mirrors next to the job.

**Try it:** [sign in with GitHub](https://groundbox.dev/signin). The free plan needs no card.
