The Actions cache

actions/cache works unmodified and is included. What a job may read and write, and the two eviction policies.

actions/cache works unmodified. So do the wrappers built on it — setup-node's cache:, setup-go, setup-python, cache/restore and cache/save. You do not change a workflow to use ours and you do not point it anywhere: a job running on our runners resolves the cache service to us.

yaml

jobs:
  build:
    runs-on: ghwarp-4vcpu-ubuntu-2404
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci

The Actions cache is included. It is not metered and does not appear as a line on your bill.

What a job can read, and what it can write

Entries are partitioned by organisation, repository and git ref. The rules follow the ones GitHub documents, with one difference noted below:

A restore looks in two places, in order: the ref the job is running on, then the default branch. The first hit wins, and a job on the default branch does not scan it twice. Unlike GitHub, a pull request's job does not read its base branch's entries, only its own and the default branch's.
A save writes to one place: the job's own ref, and never anywhere else. That is what stops a feature branch replacing the entry main depends on.
Sibling branches cannot see each other. A cache written on feature-a is not visible from feature-c, on GitHub's runners or on ours.

The scope comes from the job's own credentials rather than from anything the workflow sends, so it is not something a step can widen.

Eviction

Two policies, both mirroring GitHub's:

An entry that has not been read for seven days is removed.
An organisation over its storage quota is trimmed least-recently-read first.

Age since creation is deliberately not a policy. An entry a nightly build has restored every day for a year is doing its job, and deleting it because it is old would be the wrong answer.

Reading the Cache screen

Cache in the dashboard shows the hit rate for the period, storage used, and how many entries there are. If you are over the storage ceiling it says so, rather than silently dropping things.

A hit rate that falls is almost always a key that has started varying when it should not — a lockfile hash that includes a timestamp, or a matrix dimension that has crept into the key. The entry list is where that shows up: one key has quietly become hundreds.

What this is not

This is the Actions cache: a keyed archive your workflow restores and saves explicitly. It is not the Docker layer cache, which is a different mechanism for a different problem — see the Docker layer cache.