# Cloud Cache Action

> High-performance GitHub Action for saving and restoring CI cache bundles directly to any S3-compatible cloud or self-hosted object storage with 1:1 actions/cache parity and native Node 24 runtime.

Cloud Cache Action solves GitHub Actions cache quotas (10 GB default per repository) and egress transfer fees by letting developers store cache archives in their own S3-compatible storage tier (AWS S3, Cloudflare R2, Google Cloud Storage, Backblaze B2, Fastly, Garage S3, SeaweedFS, MinIO).

Key capabilities:
- 1:1 input and output compatibility with `actions/cache` (v4, v5, and v6).
- Native Node 24 execution (`runs: using: 'node24'`) with zero runner deprecation warnings.
- Multi-threaded Zstandard (`zstd`) compression with automatic `gzip` fallback.
- Dual-caching mode: syncs simultaneously to both remote S3 and GitHub Actions Cache tier for maximum resilience.
- Standalone sub-actions: `xSAVIKx/cloud-cache-action/restore@v1` and `xSAVIKx/cloud-cache-action/save@v1`.
- Safe POSIX key normalization: Guarantees forward slashes (`/`) in S3 keys across Windows, Linux, and macOS runners.

```yaml
- name: Cache dependencies to S3
  uses: xSAVIKx/cloud-cache-action@v1
  with:
    bucket: my-ci-cache-bucket
    endpoint: https://<account_id>.r2.cloudflarestorage.com # Or AWS, GCS, B2, MinIO
    access-key: ${{ secrets.S3_ACCESS_KEY }}
    secret-key: ${{ secrets.S3_SECRET_KEY }}
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-
```

## Documentation

- [Getting Started](https://xsavikx.github.io/cloud-cache-action/guide/getting-started.html): Quickstart guide, cache lifecycle breakdown, and standalone restore/save workflows.
- [Dual Caching Guide](https://xsavikx.github.io/cloud-cache-action/guide/dual-caching.html): Multi-tier caching across S3 and GitHub Actions Cache with backfill synchronization.
- [S3 Key Patterns](https://xsavikx.github.io/cloud-cache-action/guide/s3-key-patterns.html): Custom object key templating, prefixing, and organization-wide cache sharing.
- [Migration Guide](https://xsavikx.github.io/cloud-cache-action/guide/migration.html): 2-minute migration guide, copy-pastable AI agent migration prompt, and secrets cheat sheet.

## Storage Providers

- [AWS S3](https://xsavikx.github.io/cloud-cache-action/providers/aws-s3.html): Setup guide, bucket best practices, OIDC IAM role assumption, and lifecycle expiration.
- [Cloudflare R2](https://xsavikx.github.io/cloud-cache-action/providers/cloudflare-r2.html): Zero egress fee caching, bucket configuration best practices, and scoped API tokens.
- [Google Cloud Storage](https://xsavikx.github.io/cloud-cache-action/providers/google-cloud-storage.html): XML API interoperability, bucket best practices, and service account HMAC keys.
- [Backblaze B2](https://xsavikx.github.io/cloud-cache-action/providers/backblaze-b2.html): S3-compatible cloud storage setup, bucket lifecycle rules, and restricted application keys.
- [Fastly Object Storage](https://xsavikx.github.io/cloud-cache-action/providers/fastly-storage.html): Edge-proximate object storage caching configuration, lifecycle, and access management.
- [Garage S3](https://xsavikx.github.io/cloud-cache-action/providers/garage.html): Lightweight distributed self-hosted S3 setup, bucket quotas, and key management.
- [SeaweedFS S3](https://xsavikx.github.io/cloud-cache-action/providers/seaweedfs.html): High-capacity distributed filesystem, native TTL auto-pruning, and S3 credentials.
- [MinIO S3](https://xsavikx.github.io/cloud-cache-action/providers/minio.html): High-performance S3 object store, ephemeral CI containers, quotas, and service accounts.

## Optional

- [Full Documentation Concatenation](https://xsavikx.github.io/cloud-cache-action/llms-full.txt): Complete concatenated documentation in a single plain-text file.
- [Repository and Issue Tracker](https://github.com/xSAVIKx/cloud-cache-action): GitHub source repository, releases, and issue tracker.