Skip to content

About

High-performance GitHub Action caching to any S3-compatible storage with 1:1 actions/cache parity, Node 24 runtime, and dual-caching

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Latest commit

 

History

284 Commits

Folders and files

Repository files navigation

Cloud Cache Action documentation

Cloud Cache Action

A drop-in replacement for actions/cache that stores your CI caches in any S3-compatible bucket.

CI Tests Documentation Node Runtime License: MIT

Getting Started • Inputs and Outputs • Providers • Migration • Changelog


Quick start

- uses: xSAVIKx/cloud-cache-action@v1
  with:
    bucket: my-ci-cache-bucket
    endpoint: https://<account_id>.r2.cloudflarestorage.com # Omit for AWS S3
    access-key: ${{ secrets.S3_ACCESS_KEY }}
    secret-key: ${{ secrets.S3_SECRET_KEY }}
    path: |
      ~/.npm
      node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

The step restores the cache. A post step saves it when the job succeeds, as actions/cache does.

To use a preset, set preset instead of path, key and restore-keys. The presets are npm, yarn, pnpm, bun, pip, poetry, uv, gradle, maven, cargo and go:

- uses: xSAVIKx/cloud-cache-action@v1
  with:
    bucket: my-ci-cache-bucket
    access-key: ${{ secrets.S3_ACCESS_KEY }}
    secret-key: ${{ secrets.S3_SECRET_KEY }}
    preset: npm

The Getting Started guide tells how a restore and a save work. The Cache Presets guide lists the paths and the lockfiles of each preset.

Migrate with an AI coding agent

Paste this prompt into your coding agent, for example Claude Code, Cursor or Copilot:

Migrate all GitHub Actions cache steps in this repository to `xSAVIKx/cloud-cache-action@v1`. Discover all workflow files in `.github/workflows/`, replace `actions/cache@*` (and /restore or /save) preserving all keys, paths, and inputs, detect or ask which storage provider to configure (AWS S3, Cloudflare R2, Google Cloud Storage, Backblaze B2, Fastly Object Storage, or a self-hosted Garage, SeaweedFS, MinIO or RustFS), and provide a checklist of required GitHub Secrets.

The Migration guide has the full prompt and the secrets that each provider needs.

Why use it

  • The same inputs and outputs as actions/cache v4 to v6. Change the uses: line, add a bucket and credentials, and keep your key, path and restore-keys.
  • Your bucket, your limits. The GitHub Actions cache gives each repository 10 GB at no cost and evicts entries above the limit (GitHub docs). A bucket has the limits and the prices of your storage provider, and no cache is removed unless you remove it. With Cloudflare R2, there are no egress fees.
  • Any S3-compatible storage. AWS S3 (static keys or OIDC), Cloudflare R2, Google Cloud Storage, Backblaze B2, Fastly, and self-hosted Garage, SeaweedFS, MinIO and RustFS.
  • Fast transfers. Multi-threaded zstd compression, parallel ranged downloads and parallel multipart uploads. See Performance.
  • Safe caches. Each save stores a sha256 checksum, and the restore verifies it. Branch isolation is the same as in actions/cache. On providers that support conditional writes, two concurrent saves of one key do not overwrite each other.
  • Tools for the full cache lifecycle. Package manager presets, scheduled pruning, lookup inspection, metrics, and an optional second tier in the GitHub Actions cache.
  • A CLI for other CI systems. The cloud-cache command runs the same cache engine in Bitbucket Pipelines and other CI systems.

Storage providers

Provider Setup guide
AWS S3 Static keys or OIDC
Cloudflare R2 Cloudflare R2
Google Cloud Storage HMAC keys
Backblaze B2 Backblaze B2
Fastly Object Storage Fastly
Garage (self-hosted) Garage
SeaweedFS (self-hosted) SeaweedFS
MinIO (self-hosted) MinIO
RustFS (self-hosted) RustFS

The Storage Providers overview compares the providers. The action finds the provider, the region and the addressing style from the endpoint URL. To override the result, set provider. The Security guide gives a least-privilege policy for each provider.

Actions

Action Use
xSAVIKx/cloud-cache-action@v1 Restores, then saves in the post step.
xSAVIKx/cloud-cache-action/restore@v1 Restores only.
xSAVIKx/cloud-cache-action/save@v1 Saves only, for example with if: always() after a failed step.
xSAVIKx/cloud-cache-action/prune@v1 Deletes old caches on a schedule. See Pruning.
xSAVIKx/cloud-cache-action/inspect@v1 Tells which cache a restore would use, and why, without a restore. See Inspecting.

Inputs and Outputs lists every input and every output.

Documentation

Contributing

CONTRIBUTING.md tells how to build and test the action, and how a release is made.

License

Distributed under the MIT License. Created and maintained by Yurii Serhiichuk.

About

High-performance GitHub Action caching to any S3-compatible storage with 1:1 actions/cache parity, Node 24 runtime, and dual-caching

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages