Skip to content

The agent that grows with you

ci: pull requests restore the uv and npm caches without saving their own

ethernet13cb8cca17bb
diff --git a/.github/actions/save-pm-cache/README.md b/.github/actions/save-pm-cache/README.md
deleted file mode 100644
index e9140a813ca..00000000000
--- a/.github/actions/save-pm-cache/README.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Bundle dependency caches
-
-`setup-pm` restores uv's real cache, not the installed virtual environment.
-Its fallback keys retain the native target, OS version, and Python version.
-A metadata or dependency change can reuse compatible wheels;
-uv still resolves and installs from the frozen project lock.
-
-Bundle jobs set `save-python-cache: false` and call `save-pm-cache` after their
-build step with the `python-path`, `uv-cache-path`, and `python-cache-key` outputs.
-Both the caller and this composite use `!cancelled()` so a failed build does
-not suppress the save. Cancellation is excluded to avoid racing a dying uv
-process. A runner crash or job timeout can still prevent the save.
-
-Snapshots use a run ID, attempt, and producer job suffix because Actions caches
-are immutable. Sibling bundle workflows in one caller run must not race to save
-different contents under the same key.
-Restore tries the current dependency set's rolling snapshots first, then the
-compatible v2 prefix. There is no fallback to older cache formats. This lets
-a retry add wheels to a snapshot saved by a partially failed build. The ordinary
-automatic cache path remains available.
-
-Suffixed namespaces precede the native/dependency identity, outside production's
-restore prefix.
-
-Before saving, `python -m pm.build_env --exact-lock --cache PATH --lock-source REPO`
-deletes every entry the project's `uv.lock` cannot resolve. It keeps downloaded
-wheels the lock resolves (bundles copy the full cache for offline dependency
-installation) — `uv cache prune --ci` would discard them. Pruning happens after
-payload staging and packaging, and it does not change the staged payload.
-The same lock-exactness contract governs the bundle ship gate
-(`stage_uv_cache`) and CI's rolling snapshots, so no snapshot accumulates
-sediment for superseded pins.
-
-This is not a lockfile-aware or size-bounded cache. Old, still-referenced package
-versions can remain inside a snapshot and be copied forward. GitHub evicts whole
-cache snapshots under its retention and repository quota policies; that does
-not remove old versions inside the newest snapshot. A future size policy must
-account for the offline payload too, rather than deleting uv internals or
-promising that `prune` keeps only the current lock.
diff --git a/.github/actions/save-pm-cache/action.yml b/.github/actions/save-pm-cache/action.yml
deleted file mode 100644
index 3adc0965381..00000000000
--- a/.github/actions/save-pm-cache/action.yml
+++ /dev/null
@@ -1,35 +0,0 @@
-name: Save the PM Python dependency cache
-description: Prune to the lock and save a rolling cache after the consumer, even when it failed.
-inputs:
- python:
- description: Prepared Python used to invoke PM.
- required: true
- path:
- description: Cache directory exported by setup-pm.
- required: true
- key:
- description: Rolling snapshot key exported by setup-pm.
- required: true
-runs:
- using: composite
- steps:
- # Status checks are needed inside the composite too: the caller can
- # enter after a failed build. Never prune while cancellation kills uv.
- - name: Prune cache entries outside the project lock
- id: prune
- if: ${{ !cancelled() }}
- shell: bash
- env:
- PM_PYTHON: ${{ inputs.python }}
- PM_CACHE: ${{ inputs.path }}
- PM_LOCK_SOURCE: ${{ github.workspace }}
- # Exact-to-lock: downloaded wheels the lock resolves survive (bundles
- # copy this cache for offline installs), while superseded pins do not
- # accumulate. --ci was never usable here — it discards downloaded wheels.
- run: '"$PM_PYTHON" -m pm.build_env --exact-lock --cache "$PM_CACHE" --lock-source "$PM_LOCK_SOURCE"'
- - name: Save reusable Python dependencies
- if: ${{ !cancelled() && steps.prune.outcome == 'success' }}
- uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
- with:
- path: ${{ inputs.path }}
- key: ${{ inputs.key }}
diff --git a/.github/actions/setup-pm/action.yml b/.github/actions/setup-pm/action.yml
index ce414f4cf7e..b044d40dfc1 100644
--- a/.github/actions/setup-pm/action.yml
+++ b/.github/actions/setup-pm/action.yml
@@ -19,24 +19,24 @@ inputs:
cache:
description: Cache the verified PM tool store.
default: 'true'
+ # Pull requests restore main's caches and never save their own: a PR-scoped
+ # entry is restorable only by that PR, and the tools key hashes pm/** and
+ # this action, so every push to a PR touching them wrote a fresh store.
save-tools-cache:
description: Save the verified PM tools on success. Set false for restore-only jobs.
- # The key hashes pm/** and this action, so every push to a PR touching
- # them wrote a fresh ~100-170 MB store only that PR could restore. PRs
- # restore main's store and never write their own.
default: ${{ github.event_name == 'pull_request' && 'false' || 'true' }}
cache-python:
description: Cache uv downloads and built wheels; never cache the dependency environment.
default: 'true'
save-python-cache:
- description: Save automatically on success. Set false to save a rolling snapshot with save-pm-cache after the consumer, including on failure.
- default: 'true'
+ description: Save the uv cache on success. Set false for restore-only jobs.
+ default: ${{ github.event_name == 'pull_request' && 'false' || 'true' }}
cache-node:
description: Cache npm downloads; never cache node_modules.
default: 'true'
save-node-cache:
- description: Save automatically on success. Set false to save a consumer-scoped rolling snapshot with actions/cache/save after npm preparation.
- default: 'true'
+ description: Save the npm cache on success. Set false for restore-only jobs.
+ default: ${{ github.event_name == 'pull_request' && 'false' || 'true' }}
python-cache-dependency-glob:
description: Dependency files that invalidate the uv cache.
default: |
@@ -79,21 +79,9 @@ outputs:
python-cache-hit:
description: Exact uv dependency cache hit.
value: ${{ steps.python-cache.outputs.cache-hit || steps.python-cache-restore.outputs.cache-hit }}
- python-cache-key:
- description: Rolling snapshot key for save-pm-cache when save-python-cache is false.
- value: ${{ steps.python-cache-restore.outputs.cache-primary-key }}
- uv-cache-path:
- description: Shared uv cache directory for save-pm-cache.
- value: ${{ steps.install.outputs.uv-cache-path }}
node-cache-hit:
description: Exact npm dependency cache hit.
value: ${{ steps.node-cache.outputs.cache-hit || steps.node-cache-restore.outputs.cache-hit }}
- node-cache-key:
- description: Rolling snapshot key when save-node-cache is false.
- value: ${{ steps.node-cache-restore.outputs.cache-primary-key }}
- npm-cache-path:
- description: npm download cache directory for an explicit consumer save.
- value: ${{ steps.install.outputs.npm-cache-path }}
runs:
using: composite
steps:
@@ -171,18 +159,14 @@ runs:
# fallback must not restore a smoke run's partial dependency set.
restore-keys: ${{ inputs.cache-suffix == '' && format('setup-pm-uv-v3-production-{0}-{1}-{2}-', steps.prepare.outputs.target, steps.prepare.outputs.os-version, steps.prepare.outputs.python-version) || '' }}
- - name: Restore uv dependencies for an explicit save
+ - name: Restore uv dependency downloads and builds
id: python-cache-restore
- if: inputs.toolchain != 'node' && inputs.cache-python == 'true' && inputs.save-python-cache == 'false'
+ if: inputs.toolchain != 'node' && inputs.cache-python == 'true' && inputs.save-python-cache == 'false' && (inputs.extras != '' || inputs.test-environment == 'true')
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: ${{ steps.install.outputs.uv-cache-path }}
- # Caches are immutable. Each producer needs its own snapshot, even
- # when a caller run contains both PM Bundle and Desktop Release.
- key: setup-pm-uv-v3-${{ inputs.cache-suffix || 'production' }}-${{ steps.prepare.outputs.target }}-${{ steps.prepare.outputs.os-version }}-${{ steps.prepare.outputs.python-version }}-${{ hashFiles(inputs.python-cache-dependency-glob) || 'no-dependency-glob' }}-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
- restore-keys: |
- setup-pm-uv-v3-${{ inputs.cache-suffix || 'production' }}-${{ steps.prepare.outputs.target }}-${{ steps.prepare.outputs.os-version }}-${{ steps.prepare.outputs.python-version }}-${{ hashFiles(inputs.python-cache-dependency-glob) || 'no-dependency-glob' }}-
- ${{ inputs.cache-suffix == '' && format('setup-pm-uv-v3-production-{0}-{1}-{2}-', steps.prepare.outputs.target, steps.prepare.outputs.os-version, steps.prepare.outputs.python-version) || '' }}
+ key: setup-pm-uv-v3-${{ inputs.cache-suffix || 'production' }}-${{ steps.prepare.outputs.target }}-${{ steps.prepare.outputs.os-version }}-${{ steps.prepare.outputs.python-version }}-${{ hashFiles(inputs.python-cache-dependency-glob) || 'no-dependency-glob' }}
+ restore-keys: ${{ inputs.cache-suffix == '' && format('setup-pm-uv-v3-production-{0}-{1}-{2}-', steps.prepare.outputs.target, steps.prepare.outputs.os-version, steps.prepare.outputs.python-version) || '' }}
# Post steps run in reverse registration order: prune before cache save.
- name: Register uv cache pruning
@@ -212,15 +196,15 @@ runs:
restore-keys: |
node-cache-${{ runner.os }}-${{ steps.prepare.outputs.arch }}-npm-
- - name: Restore npm dependencies for an explicit save
+ - name: Restore npm dependency downloads
id: node-cache-restore
if: inputs.toolchain != 'python' && inputs.cache-node == 'true' && inputs.save-node-cache == 'false'
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: ${{ steps.install.outputs.npm-cache-path }}
- # Scope producers so tool-only jobs cannot replace a full desktop cache.
- key: setup-pm-npm-v1-${{ inputs.cache-suffix || 'production' }}-${{ steps.prepare.outputs.target }}-${{ steps.prepare.outputs.npm-version }}-${{ hashFiles(inputs.node-cache-dependency-path) }}-${{ github.job }}-${{ github.run_id }}-${{ github.run_attempt }}
- restore-keys: setup-pm-npm-v1-${{ inputs.cache-suffix || 'production' }}-${{ steps.prepare.outputs.target }}-${{ steps.prepare.outputs.npm-version }}-${{ hashFiles(inputs.node-cache-dependency-path) }}-${{ github.job }}-
+ key: node-cache-${{ runner.os }}-${{ steps.prepare.outputs.arch }}-npm-${{ hashFiles(inputs.node-cache-dependency-path) }}${{ inputs.cache-suffix != '' && format('-{0}', inputs.cache-suffix) || '' }}
+ restore-keys: |
+ node-cache-${{ runner.os }}-${{ steps.prepare.outputs.arch }}-npm-
- name: Install the requested Python dependencies through PM
id: dependencies
diff --git a/scripts/build/README.md b/scripts/build/README.md
index 54c110ae434..0134d164730 100644
--- a/scripts/build/README.md
+++ b/scripts/build/README.md
@@ -290,8 +290,8 @@ cache. `scripts.bundles.stage --cache PATH` (or `hermes pm bundle --cache PATH`)
selects the persistent cache explicitly. Direct staging also accepts the
provider's `UV_CACHE_DIR`; otherwise it uses the output parent's `.uv-cache`.
The PM runtime and application dependency builds receive this same cache.
-General PM staging uses `setup-pm` and `save-pm-cache` to restore and save it
-after the build, including failures, under its v2 namespace. Desktop composition
+General PM staging uses `setup-pm`, which restores and saves it automatically on
+success. Desktop composition
instead prepares the full dependency set before its single dependency snapshot
save. The packaged `uv-cache/` is a copy, not the writable build cache.
diff --git a/tests-js/setup-pm-cache.test.mjs b/tests-js/setup-pm-cache.test.mjs
index e2d185f820c..03c2b426be3 100644
--- a/tests-js/setup-pm-cache.test.mjs
+++ b/tests-js/setup-pm-cache.test.mjs
@@ -4,88 +4,58 @@ import { expect, it } from 'vitest'
const action = path => load(readFileSync(new URL(path, import.meta.url), 'utf8'))
const setup = action('../.github/actions/setup-pm/action.yml')
-const save = action('../.github/actions/save-pm-cache/action.yml')
// Evaluates the Actions expression subset these gates use, so the tests pin
// how a gate behaves rather than how it is spelled. Status functions default
// to a healthy, uncancelled run; `status` overrides them.
-const evaluate = (expression, { status = {}, ...context } = {}) => {
+const value = (expression, { status = {}, ...context } = {}) => {
const lookup = path => path.split('.').reduce(
(value, key) => (value !== null && typeof value === 'object' ? value[key] : undefined), context) ?? ''
const statuses = { always: true, success: true, failure: false, cancelled: false, ...status }
const body = String(expression).trim().replace(/^\$\{\{/, '').replace(/\}\}$/, '')
.replace(/\b(?:inputs|steps|needs|github)(?:\.[\w-]+)+/g, path => JSON.stringify(lookup(path)))
.replace(/\b(always|success|failure|cancelled)\(\)/g, (_, name) => String(statuses[name]))
- return Boolean(Function(`"use strict"; return (${body})`)())
+ return Function(`"use strict"; return (${body})`)()
}
+const evaluate = (expression, context) => Boolean(value(expression, context))
-it('restores compatible wheels without freezing a partial build under its dependency key', () => {
- const cached = setup.runs.steps.find(step => step.id === 'python-cache')
- const restored = setup.runs.steps.find(step => step.id === 'python-cache-restore')
- const prefixes = restored.with['restore-keys'].trim().split('\n')
- // Prefer this dependency set before falling back across dependency changes.
- const rollingPrefix = prefixes[0]
- expect(restored.with.key).toBe(`${rollingPrefix}\${{ github.run_id }}-\${{ github.run_attempt }}-\${{ github.job }}`)
- expect(rollingPrefix).toBe(`${cached.with.key}-`)
- expect(prefixes[1].trim()).toBe(cached.with['restore-keys'])
- for (const boundary of ['target', 'os-version', 'python-version']) {
- expect(prefixes[1]).toContain(`steps.prepare.outputs.${boundary}`)
+it('pull requests restore the caches main saves and never write their own', () => {
+ const step = id => setup.runs.steps.find(candidate => candidate.id === id)
+ const base = { toolchain: 'all', cache: 'true', 'cache-python': 'true', 'cache-node': 'true', 'test-environment': 'false', extras: 'voice' }
+ for (const [kind, saving, restoring] of [
+ ['tools', 'tools-cache', 'tools-cache-restore'],
+ ['python', 'python-cache', 'python-cache-restore'],
+ ['node', 'node-cache', 'node-cache-restore'],
+ ]) {
+ const input = `save-${kind}-cache`
+ const save = step(saving)
+ const restore = step(restoring)
+ // A PR-scoped entry is restorable only by that PR, so PRs never save.
+ for (const [event_name, saves] of [['pull_request', false], ['push', true], ['workflow_dispatch', true]]) {
+ const inputs = { ...base, [input]: value(setup.inputs[input].default, { github: { event_name } }) }
+ expect(evaluate(save.if, { inputs }), `${kind} on ${event_name}`).toBe(saves)
+ expect(evaluate(restore.if, { inputs }), `${kind} on ${event_name}`).toBe(!saves)
+ }
+ // Restore-only reads exactly what the saving step writes on main.
+ expect(restore.uses.split('@')[0]).toBe('actions/cache/restore')
+ expect(restore.with.key).toBe(save.with.key)
+ expect(restore.with['restore-keys']).toBe(save.with['restore-keys'])
+ expect(restore.with.path).toBe(save.with.path)
}
- expect(prefixes[1]).toContain("inputs.cache-suffix == ''")
- expect(prefixes[1]).not.toContain('hashFiles')
- // Only dependency-carrying callers save; tool-only jobs must not freeze an
- // empty cache under the production key (a stub exact-hit blocks real saves).
+})
+
+it('only dependency-carrying callers touch the uv cache', () => {
+ const cached = setup.runs.steps.find(step => step.id === 'python-cache')
+ // Tool-only jobs must not freeze an empty cache under the production key
+ // (a stub exact-hit blocks real saves).
const saving = { toolchain: 'all', 'cache-python': 'true', 'save-python-cache': 'true', 'test-environment': 'false' }
expect(evaluate(cached.if, { inputs: { ...saving, extras: '' } })).toBe(false)
expect(evaluate(cached.if, { inputs: { ...saving, extras: 'voice' } })).toBe(true)
expect(evaluate(cached.if, { inputs: { ...saving, extras: '', 'test-environment': 'true' } })).toBe(true)
- // A caller either saves the exact key or restores the rolling one, never both.
- for (const saveCache of ['true', 'false']) {
- const inputs = { ...saving, extras: 'voice', 'save-python-cache': saveCache }
- expect(evaluate(restored.if, { inputs })).toBe(!evaluate(cached.if, { inputs }))
- }
- expect(setup.outputs['python-cache-key'].value).toContain('steps.python-cache-restore.outputs.cache-primary-key')
-
- // A suffix-only namespace isolates smoke reads but still lets production
- // restore smoke writes through its broad dependency fallback.
+ // A suffix-only namespace isolates smoke runs from production's prefix.
const namespace = "${{ inputs.cache-suffix || 'production' }}"
- for (const template of [cached.with.key, restored.with.key, rollingPrefix]) {
- const production = template.replace(namespace, 'production')
- const smoke = template.replace(namespace, 'smoke-42-1')
- expect(production.startsWith('setup-pm-uv-v3-production-')).toBe(true)
- expect(smoke.startsWith('setup-pm-uv-v3-smoke-42-1-')).toBe(true)
- expect(smoke.startsWith('setup-pm-uv-v3-production-')).toBe(false)
- expect(production.startsWith('setup-pm-uv-v3-smoke-42-1-')).toBe(false)
- }
-})
-
-it('explicit PM saves prune to the lock and do not prune during cancellation', () => {
- const [prune, upload] = save.runs.steps
- expect(evaluate(prune.if)).toBe(true)
- expect(evaluate(prune.if, { status: { failure: true, success: false } })).toBe(true)
- expect(evaluate(prune.if, { status: { cancelled: true, success: false } })).toBe(false)
- expect(prune.run.split(/\s+/)).toEqual(expect.arrayContaining(['pm.build_env', '--exact-lock', '--cache', '--lock-source']))
- expect(prune.env.PM_PYTHON).toBe('${{ inputs.python }}')
- expect(prune.env.PM_CACHE).toBe('${{ inputs.path }}')
- expect(prune.env.PM_LOCK_SOURCE).toBe('${{ github.workspace }}')
- const pruned = outcome => ({ steps: { [prune.id]: { outcome } } })
- expect(evaluate(upload.if, pruned('success'))).toBe(true)
- expect(evaluate(upload.if, pruned('failure'))).toBe(false)
- expect(evaluate(upload.if, { ...pruned('success'), status: { cancelled: true, success: false } })).toBe(false)
- expect(upload.uses.split('@')[0]).toBe('actions/cache/save')
- expect(upload.with).toEqual({ path: '${{ inputs.path }}', key: '${{ inputs.key }}' })
-})
-
-it('explicit npm snapshots remain replaceable and isolated from toolchain-only producers', () => {
- const restored = setup.runs.steps.find(step => step.id === 'node-cache-restore')
- expect(restored).toBeDefined()
- const prefix = restored.with['restore-keys'].trim()
- expect(restored.with.key).toBe(`${prefix}\${{ github.run_id }}-\${{ github.run_attempt }}`)
- // A toolchain-only job must not shadow the desktop consumer's warm snapshot.
- for (const boundary of ['github.job', 'node-cache-dependency-path', 'cache-suffix', 'target', 'npm-version']) {
- expect(prefix).toContain(boundary)
- }
- expect(setup.outputs['node-cache-key'].value).toContain('steps.node-cache-restore.outputs.cache-primary-key')
+ expect(cached.with.key.replace(namespace, 'smoke-42-1').startsWith('setup-pm-uv-v3-production-')).toBe(false)
+ expect(cached.with['restore-keys']).toContain("inputs.cache-suffix == ''")
})
// Key isolation, offline wheel/receipt relocation and the transport action are