Caching

Caching is the primary reason to use this action. It persists IVPM’s content-addressed cache (and, optionally, the pip/uv download caches) across CI runs.

Cache key strategy

key:          <prefix>-<runner.os>-<hashFiles(cache-dependency-path)>
restore-keys: <prefix>-<runner.os>-

  • Exact hit (manifest unchanged): the cache restores fully, ivpm update is near-instant, the save step is skipped, and cache-hit is true.

  • Miss with prefix restore (deps changed): the most recent same-OS cache is restored, ivpm update fetches only the changed deps (content-addressed → no redundant work), then the new cache is saved.

  • Cold (first run): full fetch, then save.

The runner OS is part of the key because actions/cache does not restore caches across operating systems.

Why stale restores are safe

IVPM’s cache is content-addressed by commit/version (<cache>/<pkg>/<version-or-commit>/…). Restoring an out-of-date cache can never produce a wrong result: IVPM simply re-fetches the deltas (deps whose pinned commit/version isn’t already present). This is why the prefix restore-keys fallback is correct rather than best-effort.

What is and isn’t cached

Artifact

Cached?

Why

IVPM_CACHE content store (git clones, HTTP archives, GH releases)

Yes

The primary win; content-addressed, so partial restores are safe.

pip / uv download cache (~/.cache/pip, ~/.cache/uv)

Optional

Speeds the project venv build during update (cache-python).

Project venv (packages/python)

No

venvs embed absolute paths and are large; rebuilding from a warm download cache is fast and correct.

Populated packages/ workspace

No

Derived output, not a cache; cheap to rebuild from a warm IVPM_CACHE.

Limits

GitHub’s per-repository cache ceiling (10 GB) and 7-day eviction apply. The content store is the only thing that grows; stale entries fall out of the keyed caches naturally.

Cache isolation

GitHub scopes caches by branch. A cache saved on a feature branch is visible to that branch and to PRs from it, but does not leak into protected branches. Keys include runner.os and your cache-key-prefix.