CI artifact caching

Key a CI cache on snapdir id — the content-addressed ID of the directory that determines the result — so a cache hit means the inputs are provably identical, not just similarly named.

The problem

CI caches are notoriously leaky. Most are keyed on a hash of a lockfile or a branch name, which is a proxy for the inputs, not the inputs themselves. A cache key collides when two different states happen to share a name, or misses when identical states are named differently — so you either rebuild work you already have or, worse, restore a stale artifact and ship it. Validating that a restored cache actually matches the inputs that produced it is rarely done, because computing a faithful key over a whole directory is exactly the work nobody wants to reimplement per pipeline.

Why snapdir

snapdir id gives you a deterministic, content-addressed key for any directory in one command — the BLAKE3 hash of its manifest:

Keys are the content. Two dependency trees produce the same ID if and only if they are byte-for-byte identical. No proxy, no collisions from coincidental names, no misses from cosmetic differences.
Store and restore by ID. Push the built artifact under that key and pull it back on the next run; objects are deduplicated, so shared dependencies across branches are stored once.
Verified restores. Every pulled object is re-hashed on fetch, so a cache hit can never hand you a corrupt or stale artifact.

Walkthrough

Derive a cache key from the directory that determines the build — for example a resolved dependency lockfile and vendor tree:

key=$(snapdir id ./vendor)
echo "cache key: $key"

On a cache miss, build, then push the result under a key derived from its inputs so the next run can find it:

artifact_id=$(snapdir push --store s3://ci-cache/deps ./vendor)

On a later run, recompute the key from the current inputs and try to restore. If the snapshot exists in the store, pull it; otherwise fall through to a rebuild:

key=$(snapdir id ./vendor)
if snapdir pull --store s3://ci-cache/deps --id "$key" ./vendor 2>/dev/null; then
  echo "cache hit: $key"
else
  echo "cache miss: building"
  # ... run the build, then ...
  snapdir push --store s3://ci-cache/deps ./vendor
fi

Because the key and the restored content share the same content address, a hit is self-validating — there is no separate "is this cache still valid?" step.

Outcome

Cache keys become exact statements about content rather than fragile proxies, so hits are correct by construction and misses only happen when inputs genuinely changed. Shared dependencies are deduplicated across branches and runs, cutting both storage and transfer, and every restore is integrity-checked — a CI cache you can trust to never ship a stale artifact. See snapdir id for the key-derivation details.