GitHub Actions Cache
Avrea serves GitHub Actions caches from storage beside your runners. Existing
actions/cache operations in GitHub Actions jobs are routed automatically,
with no workflow changes required.
When to use Actions cache
Section titled “When to use Actions cache”Use Actions caching for reusable files that your workflow produces and Avrea does not cache automatically, such as an expensive generated test dataset.
For dependency downloads and supported build outputs, use Avrea's integrations:
These guides explain which setup-action caches and archive steps to disable.
Use the Avrea cache action
Section titled “Use the Avrea cache action”You can optionally use avrea-com/cache@v1
to restore and save reusable job outputs on Avrea runners, in GitHub Actions
or Avrea CI. To switch, replace actions/cache with
avrea-com/cache@v1, keeping your path, key, and restore-keys inputs.
The example below uses this action.
The action restores during the step and saves after a successful job. An exact
cache hit skips saving. Cache service errors warn and continue;
fail-on-cache-miss: true fails when no entry is found.
For separate restore and save steps, use avrea-com/cache/restore@v1 and
avrea-com/cache/save@v1. The actions use the same keys, version hashes, and
archive format as actions/cache through Avrea's cache proxy, so existing
compatible entries remain reusable.
The action requires updated Avrea runners with the preinstalled Avrea binary. Its restore step fails if the binary is missing, including on GitHub-hosted runners. For container jobs and Docker actions, see container setup.
See the action reference for all inputs and outputs, and Avrea CI cache limits for event support when running workflows directly in Avrea.
Example: cache generated test data
Section titled “Example: cache generated test data”Suppose your repository has a standalone Node.js script,
scripts/generate-test-data.mjs, that calculates a deterministic test dataset
from files in tests/data/ and writes it to .cache/test-dataset/.
Your tests read that generated dataset.
Cache the result to skip the calculation on subsequent runs with the same inputs. Include the generator, source data, and runtime version in the key:
jobs: test: runs-on: avrea-ubuntu-latest steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v7 id: node with: node-version: 24 package-manager-cache: false
- name: Restore generated test data uses: avrea-com/cache@v1 id: dataset with: path: .cache/test-dataset key: test-data-v1-${{ runner.os }}-${{ runner.arch }}-${{ steps.node.outputs.node-version }}-${{ hashFiles('scripts/generate-test-data.mjs', 'tests/data/**') }}
- name: Generate test data on a cache miss if: steps.dataset.outputs.cache-hit != 'true' run: node scripts/generate-test-data.mjs
- run: node --testReplace the script and paths with your project's equivalents. If generation also depends on configuration, helper scripts, or dependencies, include those inputs and the dependency lockfile in the key. The workflow must be able to regenerate the dataset whenever the cache is unavailable. An exact key avoids reusing a dataset generated from different inputs.
Supported actions
Section titled “Supported actions”Any action that uses GitHub's Cache v2 API works with no changes:
Existing caches configured through actions/setup-go, actions/setup-node,
actions/setup-python, and actions/setup-java are also supported. See
When to use Actions cache for guidance on which caches
to keep.
For Docker builds, follow the Docker build cache guide.
Cache scoping
Section titled “Cache scoping”The rules below apply to GitHub Actions jobs on Avrea runners. For workflows run directly by Avrea CI, review cache event support.
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.
Jobs and workflow runs can reuse a cache when its key and branch scope match. A later job can restore an entry after an earlier job has successfully saved it, but every consumer must handle cache misses by regenerating the files.
For outputs that another job requires, such as a compiled binary produced by a build job, use workflow artifacts and an explicit job dependency. A cache is an optimization, not a required output delivery mechanism.
Cache stats
Section titled “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 for field definitions and coverage states.
Further reading
Section titled “Further reading”For cache key patterns, restore-keys, and setup-action behavior, see
GitHub's dependency caching reference.