Skip to content

v1.0.0 – Production Release: Universal S3 Cache with 1:1 actions/cache Parity

Choose a tag to compare

View all tags
@xSAVIKx xSAVIKx released this 11 Sep 18:28
· 124 commits to main since this release
v1.0.0
aaa37da

🚀 Cloud Cache Action v1.0.0 (Production Release)

Cloud Cache Action is a production-ready, high-performance GitHub Action for saving and restoring cache artifacts to any S3-compatible cloud or self-hosted object storage with full 1:1 actions/cache parity (v4–v6) and native Node 24 execution.

✨ Highlights & Features

  • 1:1 actions/cache Parity: Complete drop-in replacement for all official inputs (path, key, restore-keys, fail-on-cache-miss, lookup-only, enableCrossOsArchive, read-only, save-always) and outputs (cache-hit, cache-primary-key, cache-matched-key).
  • Modern Node 24 Runtime: Native runs: using: 'node24' runtime with zero deprecation warnings on modern GitHub runners.
  • Universal Cloud Provider Compatibility: Live verified against:
    • AWS S3 (both static IAM credentials and GitHub Actions OIDC role assumption)
    • Cloudflare R2 (zero egress cost caching)
    • Google Cloud Storage (GCS) (via XML API and HMAC service account keys)
    • Backblaze B2
    • Fastly Object Storage
    • Garage S3 & SeaweedFS (self-hosted distributed object storage)
    • MinIO / LocalStack
  • ⚡ Dual-Caching Synchronization: Cache simultaneously across both your S3 bucket and GitHub Actions Cache tier with configurable priority (s3-first or github-first) and automatic backfill synchronization.
  • Custom S3 Key Templating: Flexible patterns such as ${GITHUB_REPOSITORY}/${prefix}${key}/${archive_filename} with support for custom environment variables (${RUNNER_OS}, ${GITHUB_JOB}).
  • Safe Cross-Platform Keys: Guarantees standard POSIX forward slashes (/) in object storage across Linux, macOS, and Windows runners.
  • Resilient Archiving & Transfer: Multi-threaded compression (zstd with automatic gzip fallback), streaming multipart uploads, and exponential backoff retries on transient network errors.
  • Modular Sub-Actions: Dedicated restore-only (restore/action.yml) and save-only (save/action.yml) workflows for custom build pipelines.

📦 Quick Start

- 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
      node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

Dual-Caching (S3 + GitHub Actions Cache)

- name: Dual Cache (S3 + GitHub Cache Fallback)
  uses: xSAVIKx/cloud-cache-action@v1
  with:
    bucket: my-ci-cache-bucket
    dual-cache: true
    restore-priority: github-first
    dual-cache-strategy: backfill
    access-key: ${{ secrets.S3_ACCESS_KEY }}
    secret-key: ${{ secrets.S3_SECRET_KEY }}
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

🧪 Verification & Reliability

  • 138 Automated Tests: Unit tests, contract parity validation, and live container integration tests.
  • Dedicated Provider Verification: Automated CI test suites running live against Amazon S3, Cloudflare R2, Google Cloud Storage, and MinIO.
  • Dogfooded: Powers caching for repository CI and documentation deployment.

Documentation: https://xsavikx.github.io/cloud-cache-action/
Created by: Yurii Serhiichuk

Assets 2
Loading