> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trunk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Caching

> The shared cache lets jobs reuse build results, so they finish faster.

## What the Runner cache supports

Trunk Runners provides support for the following cache services. Caching is enabled for the entire org with the ability to overwrite cache behavior for each repo.

| Tool | On by default | What Trunk does when it is on |
| - | - | - |
| `actions/cache` | Yes | Sends the GitHub Actions cache to the shared cache. |
| Bazel | Yes | Sets the shared cache as Bazel's remote cache. |
| sccache | No | Builds Rust code through `sccache`, with the shared cache as storage. |
| Nix | No | Adds the shared cache as a Nix binary cache, and uploads what you build. |

Cache configuration requires admin privileges. See [Cache settings](https://docs.trunk.io/runners/cache/settings.md) for more options.

### sccache

When sccache is on, Trunk sets `RUSTC_WRAPPER` and `CARGO_INCREMENTAL=0` for the
job. These values replace the values that you set in a workflow-level or job-level
`env:`. A step-level `env:` still wins.

### Bazel

Trunk uses a Bazel result from the cache only when all of its outputs are still in
the cache. If an output is missing, Bazel gets a cache miss and builds the target
again.

A job that runs in a container (`container:`) does not get the Bazel setup.

### Nix

The default Trunk runner image does not include Nix. Install it with a
[template](https://docs.trunk.io/runners/actions/templates.md), or with an installer step such as
`cachix/install-nix-action` or `DeterminateSystems/nix-installer-action`.

* Nix uses the shared cache only when the runner user is a trusted Nix user. Both
  installer actions trust the runner user by default.
* Your own Nix settings win. If your job sets its own `post-build-hook`, Trunk does
  not upload what the job builds.
* If Nix cannot get a path from the cache, it builds the path from source.
* Trunk does not cache a single store path that is larger than 2 GiB.
* A job that runs in a container (`container:`) does not get the Nix setup.

## Overriding cache behavior

Add `cache` to the `runs-on` label to override the default cache behavior for that repo:

| Value | Effect |
| - | - |
| `cache=trunk` | Use the Trunk shared cache for `actions/cache`. This is the default. |
| `cache=github` | Use the GitHub cache for `actions/cache` in that job. |

```yaml theme={"system"}
runs-on: trunk=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..cache=github
```

The `cache` option changes only `actions/cache`. Bazel, sccache, and Nix follow
your [cache settings](https://docs.trunk.io/runners/cache/settings.md). `cache=trunk` does not turn on
`actions/cache` for a repository where the setting is off.

## Which entries a job uses

By default, a job uses cache entries from its own branch and from the default
branch. A job writes only to its own branch.

For Bazel, sccache, and Nix, an admin can let a job also use entries from all
branches in the repository. See
[Which branches a job uses cache from](https://docs.trunk.io/runners/cache/settings.md#which-branches-a-job-uses-cache-from).

> [!NOTE]
>
> A fork pull request gets read-only cache access. A push to your own repository
> can write to the cache.

## Cache Storage Policy

* Trunk removes an entry that no job used for 7 days.
* Each repository can keep up to 20 GiB for each tool. When a repository goes over
  that limit, Trunk removes the least recently used entries first.
* Bazel's cache results and their outputs share one 20 GiB limit.
* Trunk removes a Nix path only when no other path in the cache refers to it.