S3 cache for GitHub Actions

The problem with the default GitHub Action cache

GitHub offers a default cache ↗ for actions, that can be used in the following way:

steps:
  - uses: actions/checkout@v4

  - uses: actions/cache@v4
    with:
      path: path/to/dependencies
      key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}

  - name: Install Dependencies
    run: ./install.sh

However this comes with a number of limitations:

• total cache size is limited to 10GB for each repository. When this limit is reached, items are evicted from the cache to make place for others. On busy repositories with large caches (rust, docker, npm, etc.), you can easily reach that size. This leads to far more cache misses, and slower execution times for your workflows.
• slow throughput: on GitHub it’s very rare to see throughputs of more than 50MB/s when uploading or restoring a cache. This means your caching steps might take 30s or more for large caches.

Introducing runs-on/cache

While the default actions/cache works fine on RunsOn, with throughput often higher than 100MB/s (twice that of GitHub) thanks to AWS network, we thought we could still improve that, and also remove the limit on cache size.

Our drop-in replacement action runs-on/cache ↗ transparently switches the storage backend to S3.

Even better, if you are running this action with RunsOn, an S3 bucket will have been created for you, and runners will automagically get access to it.

Tihs means you only need to change one line:

- uses: actions/cache@v4
- uses: runs-on/cache@v4
  with:
    ...

This is a drop-in replacement, so all the official options are supported.

This results in throughput speed between 300MB/s and 500MB/s for large cache items, and removes the limit on cache size (S3 is by definition infinite).

To avoid the S3 bucket growing indefinitely, a lifecycle rule on the bucket automatically removes items older than 10 days.

The S3 cache can also be used as a backend for Docker Buildx caching, as explained in the reference Caching page.

Usage outside RunsOn

We know a lot of GitHub Action users complaining about cache speeds and sizes, so we made sure you can use this action in any environment too.

If you want to use this in your own infrastructure, simply setup your AWS credentials with aws-actions/configure-aws-credentials ↗, then:

  - uses: aws-actions/configure-aws-credentials@v4
    ...
  - uses: runs-on/cache@v4
    with:
      ...
    env:
      RUNS_ON_S3_BUCKET_CACHE: name-of-your-bucket

The repository is available at runs-on/cache ↗ on GitHub.

Considerations

Be aware of S3 transfer costs if your runners are not in the same AWS region as your bucket.

Note: in the S3 bucket, caches are automatically prefixed with cache/$GITHUB_REPOSITORY/.