Abstract
A build cache spans two moments: restore near the start of a job and save during cleanup. bucket-cache-action makes storage, credentials, and that final save decision explicit. It supports S3 and native Google Cloud Storage, including workload-identity renewal in each phase, while keeping the bucket's access and retention policies under the operator's control. [1]
1. The problem
A job can restore dependencies with one cloud role, switch to a deployment role, and reach cleanup after the original credentials have expired or been removed. A cache implementation that relies only on the environment left behind at save time then depends on unrelated actions and their cleanup order. [1]
A useful cache may also deserve saving even when a later, unrelated step fails. Conversely, an unsuccessful dependency installation should not populate the cache just because a broad cleanup condition runs. The action lets the operator express the relevant final outcome through save-if, including the result of a step that runs after restore. [1][2]
2. The design
The main phase restores an exact key or the newest match under an ordered fallback prefix. It records the storage configuration for cleanup. The post phase reads the final save-if value but reuses the original provider, paths, and key. Exact hits, lookup-only requests, failed restores, and empty file sets do not trigger automatic uploads. Separate restore and save entry points support explicit workflow composition. [1][2]
With native S3 OIDC or GCS Workload Identity Federation configured, each phase obtains its own credentials and the provider can refresh them during transfers. The action does not put credentials in restore-to-post state. Standard AWS and Google credential sources are also supported, but those sources must remain available during cleanup. [1]
Writes are immutable: S3 uses conditional writes and GCS uses a generation precondition. Downloads pin their ranges to an object version and verify the full digest before extraction. Archives use the JavaScript tar package and Node 24's zstd implementation, avoiding a system tar or compression executable. [1]
3. Alternatives
The relevant distinction is the requirement each approach serves.
3.1 runs-on/cache
- The constraint
- RunsOn's action already supports S3. Its documented behavior includes GitHub-cache fallback when no bucket is configured and discarding existing AWS environment credentials when RUNS_ON_RUNNER_NAME is set. Operators must account for those runner-specific choices. [3]
- Our approach
- This project derives its layout from RunsOn but implements storage independently, requires an explicit bucket, and avoids runner discovery and environment-credential overrides. It also offers native GCS federation. [1]
- The tradeoff
- RunsOn's automatic discovery and fallback are useful inside that ecosystem. This action deliberately requires more explicit provider and identity configuration.
3.2 actions/cache
- The constraint
- The hosted cache applies GitHub's documented branch access rules, key lookup, and eviction policy. It does not expose an operator-selected S3 or GCS bucket as its storage backend. [4]
- Our approach
- The action stores immutable objects in the selected bucket and lets the operator configure retention and namespace access through cloud policy. [1]
- The tradeoff
- GitHub's managed cache handles its own trust scopes. Bucket users must enforce writer isolation with IAM; matching key names alone do not recreate those protections.
3.3 Separate cloud upload and download scripts
- The constraint
- A file-transfer script leaves archive integrity, fallback lookup, post-job state, and credential lifetime to each workflow author.
- Our approach
- The shared action supplies these mechanisms and evaluates the final save condition in its cleanup entry point. [1][2]
- The tradeoff
- A simple script remains adequate for a small, fixed artifact with different lifecycle semantics. This action is for reusable cache objects, not general artifact publishing.
4. Boundaries & adoption
An archive digest detects corruption, not a malicious authorized writer. Anyone who can populate a cache may influence executable dependencies read by a later job. Separate untrusted pull-request writers from trusted build or deployment caches through bucket and identity policy. [1]
Buckets must already exist. Configure retention and abandoned-upload cleanup, and account for transfer cost and storage location. The action's cache format differs from RunsOn's, so a migration starts cold. Transfer timeouts do not cover local archive creation or extraction. The repository's emulator and workflow tests are described in its documentation; this catalog does not claim an independent cloud benchmark. [1]
5. References
Sources reviewed September 12, 2026. Mathematic source links retain the reviewed revision.
- [1]Bucket cache: lifecycle, identity, storage, trust model, and origin Mathematic Inc. · 714dccf2
- [2]Action manifest: inputs and post-job entry point Mathematic Inc. · 714dccf2
- [3]
- [4]GitHub: cache access, key matching, and eviction docs.github.com