A drop-in replacement for actions/cache that stores your CI caches in any S3-compatible bucket.
Getting Started • Inputs and Outputs • Providers • Migration • Changelog
- 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: npmThe Getting Started guide tells how a restore and a save work. The Cache Presets guide lists the paths and the lockfiles of each preset.
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.
- The same inputs and outputs as
actions/cachev4 to v6. Change theuses:line, add a bucket and credentials, and keep yourkey,pathandrestore-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
zstdcompression, 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-cachecommand runs the same cache engine in Bitbucket Pipelines and other CI systems.
| 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.
| 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.
- Getting Started: paths, how a restore and a save work, metrics, and the job summary.
- Storage Providers: compare the nine providers, their credentials and their endpoints.
- Dual Caching: use the S3 bucket and the GitHub Actions cache together.
- S3 Key Templating: change the object key layout.
- How Caches Are Stored: checksums, concurrent saves, metadata and tags, and streaming.
- Performance and Benchmarks: transfer settings and measured times.
- The cloud-cache CLI: use the cache in other CI systems.
- Bitbucket Pipelines: cache Bitbucket builds in your own S3 bucket.
- Upgrading: notes for each
v1release. - FAQ: short answers to common questions.
- Comparison: Cloud Cache Action compared with other S3 cache actions.
CONTRIBUTING.md tells how to build and test the action, and how a release is made.
Distributed under the MIT License. Created and maintained by Yurii Serhiichuk.