Skip to content

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.

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.

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.

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:

workflow.yml
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 --test

Replace 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.

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.

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.

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.

For cache key patterns, restore-keys, and setup-action behavior, see GitHub's dependency caching reference.