# GitHub Actions Cache

import { Aside } from '@astrojs/starlight/components';

Avrea accelerates the GitHub Actions cache by intercepting cache API requests and serving them from colocated storage. Workflows using `actions/cache@v4+` and language setup actions work with no workflow changes.

## On Avrea runners

On Avrea runners, cache requests from `actions/cache@v4+` are transparently routed to a local cache proxy instead of GitHub's Azure blob storage. This also applies to caching built into setup actions:

```yaml
- uses: actions/setup-go@v7
  with:
    go-version: '1.25'
    # Built-in dependency caching works automatically

- uses: actions/setup-node@v7
  with:
    node-version: '24'
    cache: 'npm'
    # npm dependency cache works automatically
```

## Supported actions

Any action that uses GitHub's Cache v2 API works with no changes:

- [`actions/cache@v4+`](https://github.com/actions/cache)
- [`actions/cache/save@v4+`](https://github.com/actions/cache) and [`actions/cache/restore@v4+`](https://github.com/actions/cache)
- `actions/setup-go`, `actions/setup-node`, `actions/setup-python`, `actions/setup-java` (with caching enabled)
- Docker Buildx with `type=gha` cache backend

## Example workflow

A typical workflow with caching, with no workflow changes:

```yaml title="workflow.yml"
jobs:
  build:
    runs-on: avrea-ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: 'npm'

      - run: npm ci
      - run: npm test
```

## Performance

Avrea's colocated cache is significantly faster than GitHub's.
Expect up to 5x faster cache restore times on Avrea.
Restore speeds scale with cache size.

## Compatibility

Any action or tool that uses GitHub's Cache v2 API works with Avrea's cache proxy.
This includes first-party actions, third-party actions, and build tools that integrate with the GitHub Actions cache API.
No forks or wrappers are needed. If it works on GitHub, it works on Avrea.

## Cache scoping

Caches are scoped by **repository** and **Git ref** (branch or tag), matching GitHub's native behavior:

- The **default branch** can read and write caches.
- **Feature branches** can read caches from the default branch and write to their own scope.
- **Pull requests** can restore caches from the base branch and the default branch.
- Sibling and child branches cannot access each other's caches.
- Caches are keyed by `(key, version)` and are immutable once created.
- There is no cross-repository cache access. Each repository has its own isolated namespace.

Multiple workflow runs in the same repository and branch share caches.

## Cache stats

Run and job cache stats show restore hit rate, bytes served and written,
transfer errors, and recent requested-key diagnostics. See
[Cache Stats](/cache/stats/) for field definitions and coverage states.

## Cross-job caching

Caches are shared across jobs in the same workflow and across workflow runs. A common pattern is saving the cache in a build job and restoring it in test jobs:

```yaml title="workflow.yml"
jobs:
  build:
    runs-on: avrea-ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/cache@v6
        with:
          path: ~/.npm
          key: npm-${{ hashFiles('**/package-lock.json') }}
      - run: npm ci

  test:
    needs: build
    runs-on: avrea-ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/cache@v6
        with:
          path: ~/.npm
          key: npm-${{ hashFiles('**/package-lock.json') }}
      - run: npm ci
      - run: npm test
```

## Further reading

For details on cache key patterns, `restore-keys`, and how `setup-*` actions handle caching, see GitHub's [Dependency caching reference](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching).
Everything described there works identically on Avrea runners.