gha-cache-proof 1.0.0

GitHub Actions cache compatibility checker and local cache-store receipt tool for offline CI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

# 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

```powershell
cargo install gha-cache-proof --locked
```

## Commands

Save a local cache entry:

```powershell
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:

```powershell
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:

```powershell
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