gha-cache-proof

gha-cache-proof checks and emulates GitHub Actions cache behavior with receipt-backed local evidence.

It is the cache boundary for offline CI work:

• use gha-workflow-proof to find cache steps in workflow YAML;
• use gha-cache-proof check-workflow to prove cache keys, restore keys, path globs, cache versions, and store lookup behavior;
• use gha-cache-proof restore / save inside local runners such as ci-forge to model actions/cache, actions/cache/restore, and actions/cache/save.

Install

cargo install gha-cache-proof --locked

Commands

Save a local cache entry:

gha-cache-proof save `
  --store .ci-forge/cache `
  --workspace . `
  --reference refs/heads/main `
  --key Linux-cargo-abc123 `
  --path target `
  --path ~/.cargo/registry

Restore from the current branch, then default branch, using exact and prefix matches:

gha-cache-proof restore `
  --store .ci-forge/cache `
  --workspace . `
  --reference refs/heads/feature `
  --default-branch main `
  --key Linux-cargo-new `
  --restore-key Linux-cargo- `
  --path target `
  --format json `
  --output target/cache-proof.json

Check workflow cache steps without mutating the workspace:

gha-cache-proof check-workflow `
  --repo . `
  --workspace . `
  --store .ci-forge/cache `
  --workflow .github/workflows/ci.yml `
  --format markdown

What It Models

• actions/cache, actions/cache/restore, and actions/cache/save step shape.
• Required key and path inputs.
• Multiline restore-keys, path lists, and glob path expansion.
• Cache key length limit.
• Cache version hashing from path list, compression, and cross-OS archive setting.
• Search order: current ref exact/prefix key, current ref restore keys, then base/default branch scopes.
• Exact hit output as cache-hit=true, partial restore as cache-hit=false, and miss as an empty string.
• lookup-only and fail-on-cache-miss.
• Branch/ref cache isolation for current, base, and default refs.
• Local cache-store index under index.json plus copied file snapshots under entries/<id>/files.
• Template evaluation for workflow key, restore-keys, and path values through gha-expression-proof.

Scope

gha-cache-proof is not GitHub's cache service and does not talk to GitHub APIs. It intentionally models the public behavior needed by local runners and compatibility tests:

• no network cache upload or download;
• no cache billing or quota enforcement beyond receipts;
• no tar/zstd archive bit-for-bit compatibility promise;
• no secret scanning of cache contents.

The receipt is the contract: it explains the key, version, accessible scopes, match kind, copied files, and checks.

References

The 1.0 behavior follows GitHub's public dependency caching reference and the official actions/cache README:

• https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching
• https://github.com/actions/cache