Caching

actions/cache

actions/cache, actions/cache/restore and actions/cache/save work without changes, and so does every action built on them, like actions/setup-node with cache: npm. Keys, restore keys and paths behave as they do on GitHub.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ hashFiles('requirements.txt') }}
    restore-keys: pip-

Which branch reads what

A cache belongs to the branch whose job saved it, the same way it does on GitHub:

• A job looks in its own branch’s cache first, then in the default branch’s.
• A pull request reads the default branch’s cache but never writes to it. What it saves stays with the pull request.
• A saved key isn’t overwritten. To save something new, change the key, for example with a hash of your lockfile.

Folder caching

On top of actions/cache, every job gets these folders back from earlier runs, with no change to the workflow. Installs and builds pick up where the last run on your default branch left off.

Every job starts with them. They’re saved only after a job that passed on your default branch, from a push, a schedule or a manual run, so a pull request never changes what the next job starts from. If restoring or saving a folder goes wrong, the job carries on without it.

Docker layer caching

Docker builds with Buildx can keep their layers in the same cache with type=gha. Set up Buildx and point the build at it:

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    context: .
    push: false
    cache-from: type=gha
    cache-to: type=gha,mode=max

Layers follow the same branch rules as the rest of the cache.

Size and how long it’s kept

• Each repository keeps up to 10 GB, on every plan.
• A cache that no job used for seven days is removed.

When a repository is full, the caches used least recently go first. You see what’s cached, and how often jobs find it, on the Caching page in the dashboard. Cache storage isn’t billed separately.