[eserscor]

Description

Add a separate 150,000,000,000-byte archived-storage budget per OS for sccache using the shared cache actions. Each OS's architectures and build variants share that OS's budget. Unused capacity cannot be borrowed across OSes, and total managed storage can exceed 150 GB when multiple OSes participate. The existing per-run 10G local cache, build matrices/tests/Metal coverage, vcpkg, and other cache namespaces are unchanged.

• Run generic serialized sccache-maintenance.yml hourly, independently of any specific build workflow. Future OS/build callers participate automatically through the shared key format; no workflow-name registration or OS allowlist is needed. Manual dispatch defaults to dry run.
• Fully paginate the sccache-v1- namespace. Only well-formed sccache-v1-<OS>-<arch>-<identity>-<commit> snapshots on refs/heads/main count toward the corresponding OS's budget. Legacy macos-sccache-v1-/v2- pilot snapshots and all other refs/namespaces are excluded and untouched; there are no pilot-branch special cases.
• For each over-budget OS, evict its oldest main generations first, preferentially preserving each compatibility prefix's newest baseline. OS, architecture, and hashed build/compiler identity remain part of the compatibility prefix. If an OS's baselines alone exceed its budget, warn and evict its oldest baselines. Under-budget OSes are not evicted to satisfy another OS's budget.
• Report current and planned storage per OS. Delete only scoped exact cache IDs; propagate API errors and recheck each OS's storage after cleanup. Keep actions: write isolated to the trusted-main scheduled/manual maintenance job. PRs run regression tests with read-only permissions and cannot run cleanup.
• Use Python's standard library and the preinstalled gh CLI; no runtime package installation.

Guarantee: these are soft caps, not atomic GitHub storage quotas. Uploads can run concurrently with cleanup, and scheduled runs can be delayed. An OS's storage can temporarily exceed 150 GB between hourly maintenance runs; an over-budget post-cleanup inventory fails visibly, identifies the affected OSes, and subsequent maintenance retries.

Validation (Windows, isolated Python 3.13 environment):

• python -m unittest discover -s .github\scripts -p test_prune_sccache.py -v — passed, 18 tests. Coverage includes the exact 150,000,000,000-byte default; independent OS budgets; combining architectures/builds within an OS; multiple simultaneously over-budget OSes; preserving healthy OSes; allowing combined storage above 150 GB when every OS is within budget; scope/ref guards; aggregate limits; generations; pagination/deduplication; ordering; oversized baselines; dry runs; API failures; concurrent uploads; and subprocess error propagation.
• python -m ruff check .github\scripts\prune_sccache.py .github\scripts\test_prune_sccache.py — passed.
• python -m ruff format --check .github\scripts\prune_sccache.py .github\scripts\test_prune_sccache.py — passed.
• actionlint .github\workflows\sccache-maintenance.yml — passed with actionlint 1.7.12 on the unchanged workflow in the preceding per-OS update.
• git diff --check and git diff --cached --check — passed before commit.
• $env:GITHUB_REPOSITORY='microsoft/onnxruntime'; python .github\scripts\prune_sccache.py | Select-Object -First 2 — read-only live dry run passed: macOS has 99,564,983,312 bytes scoped; zero proposed evictions at the 150 GB per-OS budget. These totals exclude legacy pilot snapshots.

No live caches were deleted and no workflows were manually triggered. Native builds/tests were not run because build behavior is unchanged.

Motivation and Context

The shared sccache actions from #33811 publish immutable snapshots of the whole local cache on successful main builds. The local size bound does not bound aggregate GitHub archived storage, so unchanged compatibility prefixes accumulate generations. This adds a temporary 150 GB per-OS retention budget that supports both today's macOS builds and future OS/build adopters without platform-specific cleanup logic.

[Copilot]

🟡 Changes recommended

Pagination by mutable access time can skip caches during concurrent restores, undercounting storage and allowing cleanup to succeed while an OS remains over budget.

1 open issue

• Use stable pagination ordering to avoid undercounting storage · New

What changed in this PR

Adds independent 150 GB soft storage caps per OS for archived snapshots produced by the shared sccache actions, without changing local cache limits or build behavior.

Changes:

• Adds scoped cache inventory and eviction logic that preferentially preserves each compatibility prefix’s newest snapshot.
• Introduces hourly maintenance with trusted-main write permissions, read-only PR tests, and manual dry runs by default.
• Adds regression tests and documents per-OS budgets, exclusions, and concurrency limitations.

File	Description
.github/​workflows/​sccache-maintenance.yml	Schedules cleanup and separates read-only tests from privileged maintenance.
.github/​scripts/​test_prune_sccache.py	Tests budgets, eviction selection, scope guards, pagination, and failures.
.github/​scripts/​prune_sccache.py	Implements inventory, per-OS eviction plans, deletion, and post-cleanup checks.
.github/​actions/​setup-sccache/​README.md	Documents retention policy, soft-cap guarantees, and preview usage.

_{Review effort: Balanced}