ENH: Automatic GitHub Actions cache cleanup for closed/merged PRs

[hjmjohnson]

Adds two complementary workflows that free the repository's 10 GB GitHub Actions cache budget automatically, so cache saves in long-running PRs (ccache, ExternalData, etc.) don't silently fail with "Cache reservation failed: You have reached your configured budget, your cache is now read only".

Pattern follows the GitHub documentation for force-deleting cache entries: https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#force-deleting-cache-entries.

Motivation

ITK's per-repo Actions cache is capped at 10 GB (GitHub default). A single Pixi+ARM cycle produces roughly:

Cache	Typical size
ccache-v4-Linux-pixi-cxx-<sha>	~2.2 GB
ccache-v4-Windows-pixi-cxx-<sha>	~3.6 MB
ccache-v4-macOS-pixi-cxx-<sha>	~1.6 GB
ccache-v4-Linux-Ubuntu-24.04-arm-<sha>	~330 MB × multiple
ccache-v4-macOS-*-<sha>	~1.6 GB
externaldata-v<ver>-<sha> (from #6109)	~0.5–1 GB

Multiplied by open PRs, the 10 GB cap is reached quickly. On PR #6109's dffb9bd1fd run, every Pixi and ARM cache save failed for this reason, despite the caching being wired correctly.

Manually sweeping closed-PR caches frees ~6 GB at a time, but that's not sustainable. These two workflows automate it.

What each workflow does

.github/workflows/cleanup-pr-caches.yml (event-driven)

• Trigger: pull_request: types: [closed]
• Action: enumerate caches for refs/pull/<N>/merge and DELETE each
• Typical runtime: 2–5 seconds
• Permissions: actions: write, contents: read
• No overhead on regular build/test runs.

.github/workflows/cleanup-stale-caches-nightly.yml (safety net)

• Trigger: cron: '0 6 * * *' (06:00 UTC) + workflow_dispatch
• Action: scan every refs/pull/<N>/merge cache; for each, check PR state; if state != OPEN and closedAt < now - 3 days, delete
• The 3-day grace period lets anyone spot-rerun a just-merged PR before its caches vanish
• Catches edge cases the on-close workflow misses (outages, pre-existing orphans, unusual close paths)
• Permissions: actions: write, pull-requests: read

Robustness properties

• Ref-scoped delete. DELETE /repos/{owner}/{repo}/actions/caches/{cache-id} targets one cache entry at a time; the enumeration is filtered by ref=refs/pull/N/merge, so refs/heads/main or other PR refs can never be touched by the on-close path.
• Idempotent. A second invocation (retry, duplicate event) finds 0 matching caches and exits 0.
• Works for PRs from forks. The pull_request event runs in the upstream repo context with the upstream's GITHUB_TOKEN, which has cache delete permissions on the upstream's cache store (where the caches actually live).
• Terminal. A reopened PR gets fresh cache entries keyed on new commits; deletions target the previous-closure era only.
• Permissions-minimal. On-close: actions: write, contents: read. Nightly: adds pull-requests: read. Neither can push code, comment, or modify anything outside Actions storage.

Verification

Manually dry-run the on-close logic against a recently-closed PR to confirm it finds and removes caches:

```bash
PR_REF=refs/pull/6093/merge # merged 2026-04-23
gh api "repos/InsightSoftwareConsortium/ITK/actions/caches?ref=${PR_REF}"
--jq '.actions_caches[] | {id, key, size_mb: (.size_in_bytes / 1048576 | floor)}'
```

(In this PR's context #6093's caches were already manually swept as part of the investigation that motivated this PR.)

After merge, an end-to-end verification is to close a test PR and confirm its caches disappear within seconds.

Ecosystem impact (follow-up)

The same pattern could be added to the shared InsightSoftwareConsortium/ITKRemoteModuleBuildTestPackageAction workflows so all 20+ remote-module repos inherit cache cleanup in one change. Deferred to a separate PR per user request.

[hjmjohnson]

ITK.Linux failed at 12m on a PR that only adds two .github/workflows/*.yml files — no C++ / CMake / test changes. This is the known Azure dashboard-script flake (ci_completed_successfully treating build warnings as fatal, itk_common.cmake:628). Re-triggering.

/azp run ITK.Linux

[hjmjohnson]

@greptileai review this draft before I make it official

[hjmjohnson]

/azp run ITK.Linux

[hjmjohnson]

@dzenanz A little more house cleaning. This is somewhat orthogonal to the other cache cleanups, but helps to make sense of the caches that are retained. After a merge is done, the cache for that PR can never be reused, so we should not keep it around.

[dzenanz]

Description sounds good. I did not take a close look at the code.

[hjmjohnson]

@dzenanz This is recommended to keep costs down (savings of a few GB at $.008/GB/day, so not much). I like it mostly to remove "dead weight" caches that can never be hit again.