Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Remove caches belonging to closed PRs and deleted branches (#658)

Dee16adcc7e4700
diff --git a/.github/workflows/cache-cleanup.yml b/.github/workflows/cache-cleanup.yml
new file mode 100644
index 000000000..6e54e5f20
--- /dev/null
+++ b/.github/workflows/cache-cleanup.yml
@@ -0,0 +1,37 @@
+name: Remove finished branch caches
+
+on:
+ pull_request_target:
+ types: [closed]
+ delete:
+
+permissions:
+ contents: read
+ actions: write
+ pull-requests: read
+
+jobs:
+ cleanup:
+ if: github.event_name == 'pull_request_target' || github.event.ref_type == 'branch'
+ runs-on: ubuntu-22.04
+ timeout-minutes: 5
+ steps:
+ # pull_request_target uses trusted default-branch code only. Never check out
+ # or execute the closed PR's head; the PR number is only an API lookup key.
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ github.event.repository.default_branch }}
+ sparse-checkout: /scripts/prune-finished-caches.py
+ sparse-checkout-cone-mode: false
+ - name: Remove closed-PR caches
+ if: github.event_name == 'pull_request_target'
+ env:
+ GH_TOKEN: ${{ github.token }}
+ PR_NUMBER: ${{ github.event.pull_request.number }}
+ run: python3 scripts/prune-finished-caches.py --pull-request "$PR_NUMBER" --apply
+ - name: Remove deleted-branch caches
+ if: github.event_name == 'delete'
+ env:
+ GH_TOKEN: ${{ github.token }}
+ DELETED_BRANCH: ${{ github.event.ref }}
+ run: python3 scripts/prune-finished-caches.py --deleted-branch "$DELETED_BRANCH" --apply
diff --git a/docs/validation-and-release.md b/docs/validation-and-release.md
index 8fdc1f390..b9a73eefa 100644
--- a/docs/validation-and-release.md
+++ b/docs/validation-and-release.md
@@ -78,6 +78,15 @@ When installation is needed, hosted jobs use the extracted SDK directly instead
of copying it into the runner's discarded local tool cache. Authentication still
runs normally; self-hosted runners retain the upstream tool-cache behavior.
+Closing a PR removes caches scoped to that PR's merge ref. Deleting a branch
+removes caches scoped to that absent branch. These finished-work caches cannot
+warm future releases from `main`; retaining them crowds the repository's cache
+storage. Cleanup uses default-branch code, checks the PR/branch state before and
+after listing, and deletes only IDs returned for that exact ref. The default
+branch, tags, open PRs and existing branches are preserved. For a read-only preview,
+run `python3 scripts/prune-finished-caches.py --repo OWNER/REPO --pull-request N`
+or use `--deleted-branch NAME`; `--apply` performs the selected cleanup.
+
### Package Desktop while final checks run
When the final implementation is pushed, start `make release-desktop ARGS="--prepare"`
diff --git a/scripts/prune-finished-caches.py b/scripts/prune-finished-caches.py
new file mode 100644
index 000000000..aa0ff6133
--- /dev/null
+++ b/scripts/prune-finished-caches.py
@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Remove caches scoped to a closed PR or a branch that no longer exists.
+
+Dry-run by default. All metadata is checked before deleting immutable cache IDs;
+main, tags, open PRs and existing branches cannot be selected by this command.
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import time
+from urllib.parse import quote, urlencode
+
+
+class NotFound(RuntimeError):
+ pass
+
+
+class Client:
+ def __init__(self, repository, budget=90):
+ if not re.fullmatch(r'[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+', repository):
+ raise ValueError('repository must be owner/name')
+ if any(part in {'.', '..'} for part in repository.split('/')):
+ raise ValueError('invalid repository')
+ self.repository = repository
+ self.deadline = time.monotonic() + budget
+
+ def api(self, path='', method='GET'):
+ remaining = self.deadline - time.monotonic()
+ if remaining <= 0:
+ raise TimeoutError('cache cleanup budget exhausted')
+ endpoint = f'repos/{self.repository}' + (f'/{path}' if path else '')
+ result = subprocess.run(['gh', 'api', '--method', method, endpoint],
+ capture_output=True, text=True, timeout=min(20, remaining))
+ if result.returncode:
+ if re.search(r'\(HTTP 404\)', result.stderr):
+ raise NotFound(endpoint)
+ raise RuntimeError(f'{method} {path or "repository"} failed')
+ return json.loads(result.stdout) if result.stdout.strip() else None
+
+
+def target_ref(client, pull_request=None, deleted_branch=None):
+ repository = client.api()
+ if not isinstance(repository, dict) or repository.get('full_name', '').lower() != client.repository.lower():
+ raise ValueError('repository identity differs')
+ default = repository.get('default_branch')
+ if not isinstance(default, str) or not default:
+ raise ValueError('repository default branch is unavailable')
+ if (pull_request is None) == (deleted_branch is None):
+ raise ValueError('select exactly one closed PR or deleted branch')
+ if pull_request is not None:
+ if type(pull_request) is not int or pull_request <= 0:
+ raise ValueError('pull request number must be positive')
+ return f'refs/pull/{pull_request}/merge'
+ if not isinstance(deleted_branch, str) or not deleted_branch:
+ raise ValueError('invalid branch name')
+ if deleted_branch == default:
+ raise ValueError('the default branch cannot be pruned')
+ ref = f'refs/heads/{deleted_branch}'
+ result = subprocess.run(['git', 'check-ref-format', ref], capture_output=True, timeout=10)
+ if result.returncode:
+ raise ValueError('invalid branch name')
+ return ref
+
+
+def finished(client, ref):
+ match = re.fullmatch(r'refs/pull/([1-9][0-9]*)/merge', ref)
+ if match:
+ data = client.api(f'pulls/{match[1]}')
+ if not isinstance(data, dict) or data.get('state') not in {'open', 'closed'}:
+ raise ValueError('pull request state is unavailable')
+ return data['state'] == 'closed'
+ if not ref.startswith('refs/heads/'):
+ raise ValueError('only branch and pull-request cache refs are supported')
+ try:
+ data = client.api('git/ref/' + quote(ref.removeprefix('refs/'), safe='/'))
+ except NotFound:
+ return True
+ if not isinstance(data, dict) or data.get('ref') != ref:
+ raise ValueError('branch identity differs')
+ return False
+
+
+def entries(client, ref):
+ result = []
+ seen = set()
+ for page in range(1, 21):
+ query = urlencode(dict(ref=ref, per_page=100, page=page))
+ data = client.api(f'actions/caches?{query}')
+ caches = data.get('actions_caches') if isinstance(data, dict) else None
+ if not isinstance(caches, list):
+ raise ValueError('cache inventory is unavailable')
+ for cache in caches:
+ if not isinstance(cache, dict) or cache.get('ref') != ref:
+ raise ValueError('cache inventory escaped the requested ref')
+ identifier, size = cache.get('id'), cache.get('size_in_bytes')
+ if type(identifier) is not int or identifier <= 0 or identifier in seen:
+ raise ValueError('invalid or duplicate cache identity')
+ if type(size) is not int or size < 0:
+ raise ValueError('invalid cache size')
+ seen.add(identifier)
+ result.append(dict(id=identifier, size_in_bytes=size))
+ if len(caches) < 100:
+ return result
+ raise ValueError('cache inventory exceeded its page budget')
+
+
+def prune(client, *, pull_request=None, deleted_branch=None, apply=False):
+ ref = target_ref(client, pull_request, deleted_branch)
+ report = dict(repository=client.repository, ref=ref, status='skipped',
+ removed_ids=[], removed_bytes=0)
+ if not finished(client, ref):
+ return dict(report, reason='pull request or branch is still active')
+ selected = entries(client, ref)
+ # A PR can reopen or a deleted branch can be recreated while listing caches.
+ if not finished(client, ref):
+ return dict(report, reason='pull request or branch became active while listing')
+ report.update(status='ready', selected_ids=[c['id'] for c in selected],
+ selected_bytes=sum(c['size_in_bytes'] for c in selected))
+ if not apply:
+ return report
+ for cache in selected:
+ try:
+ client.api(f'actions/caches/{cache["id"]}', method='DELETE')
+ except NotFound:
+ continue # Already evicted/deleted; never substitute another cache.
+ report['removed_ids'].append(cache['id'])
+ report['removed_bytes'] += cache['size_in_bytes']
+ report['status'] = 'passed'
+ return report
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--repo', default=os.environ.get('GITHUB_REPOSITORY'))
+ target = parser.add_mutually_exclusive_group(required=True)
+ target.add_argument('--pull-request', type=int)
+ target.add_argument('--deleted-branch')
+ parser.add_argument('--apply', action='store_true')
+ args = parser.parse_args()
+ if not args.repo:
+ parser.error('--repo or GITHUB_REPOSITORY is required')
+ try:
+ result = prune(Client(args.repo), pull_request=args.pull_request,
+ deleted_branch=args.deleted_branch, apply=args.apply)
+ except (OSError, ValueError, RuntimeError, subprocess.SubprocessError) as error:
+ parser.exit(1, f'cache cleanup failed: {error}\n')
+ print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/tests/test_prune_finished_caches.py b/scripts/tests/test_prune_finished_caches.py
new file mode 100644
index 000000000..a61b81c59
--- /dev/null
+++ b/scripts/tests/test_prune_finished_caches.py
@@ -0,0 +1,170 @@
+"""Finished CI caches cannot be confused with reachable branch or release caches."""
+import copy
+import importlib.util
+import json
+from pathlib import Path
+import subprocess
+from types import SimpleNamespace
+import unittest
+from unittest.mock import patch
+from urllib.parse import parse_qs, urlsplit
+
+spec = importlib.util.spec_from_file_location('cache_pruner', Path(__file__).resolve().parents[1] / 'prune-finished-caches.py')
+pruner = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(pruner)
+
+
+class FakeClient:
+ repository = 'owner/repo'
+
+ def __init__(self, ref='refs/pull/17/merge', states=None, pages=None):
+ self.ref = ref
+ self.states = list(states or [False, False]) # whether the source is active
+ self.pages = pages if pages is not None else [[dict(id=101, ref=ref, size_in_bytes=4096)]]
+ self.calls = []
+ self.missing = set()
+
+ def api(self, path='', method='GET'):
+ self.calls.append((method, path))
+ if not path:
+ return dict(full_name=self.repository, default_branch='main')
+ if path.startswith('pulls/'):
+ return dict(state='open' if self.states.pop(0) else 'closed')
+ if path.startswith('git/ref/'):
+ if self.states.pop(0):
+ return dict(ref=self.ref)
+ raise pruner.NotFound('deleted branch')
+ if method == 'DELETE':
+ if int(path.rsplit('/', 1)[1]) in self.missing:
+ raise pruner.NotFound('evicted')
+ return None
+ query = parse_qs(urlsplit(path).query)
+ if query['ref'] != [self.ref] or query['per_page'] != ['100']:
+ raise AssertionError('inventory request changed scope')
+ return dict(actions_caches=copy.deepcopy(self.pages[int(query['page'][0]) - 1]))
+
+ @property
+ def deleted(self):
+ return [path for method, path in self.calls if method == 'DELETE']
+
+
+class FinishedCacheTests(unittest.TestCase):
+ def test_closed_pr_deletes_only_listed_immutable_ids(self):
+ client = FakeClient()
+ result = pruner.prune(client, pull_request=17, apply=True)
+ self.assertEqual(result['status'], 'passed')
+ self.assertEqual(result['removed_ids'], [101])
+ self.assertEqual(result['removed_bytes'], 4096)
+ self.assertEqual(client.deleted, ['actions/caches/101'])
+
+ def test_deleted_branch_has_no_live_git_reference(self):
+ client = FakeClient(ref='refs/heads/feature/cache&probe')
+ result = pruner.prune(client, deleted_branch='feature/cache&probe', apply=True)
+ self.assertEqual(result['status'], 'passed')
+ self.assertIn(('GET', 'git/ref/heads/feature/cache%26probe'), client.calls)
+ self.assertEqual(client.deleted, ['actions/caches/101'])
+
+ def test_open_pr_and_existing_branch_do_not_even_list_caches(self):
+ for selector, ref in [(dict(pull_request=17), 'refs/pull/17/merge'),
+ (dict(deleted_branch='work'), 'refs/heads/work')]:
+ with self.subTest(selector=selector):
+ client = FakeClient(ref=ref, states=[True])
+ self.assertEqual(pruner.prune(client, apply=True, **selector)['status'], 'skipped')
+ self.assertFalse(any('actions/caches' in p for _, p in client.calls))
+
+ def test_reopened_pr_and_recreated_branch_cancel_pending_deletions(self):
+ for selector, ref in [(dict(pull_request=17), 'refs/pull/17/merge'),
+ (dict(deleted_branch='work'), 'refs/heads/work')]:
+ with self.subTest(selector=selector):
+ client = FakeClient(ref=ref, states=[False, True])
+ result = pruner.prune(client, apply=True, **selector)
+ self.assertEqual(result['status'], 'skipped')
+ self.assertEqual(client.deleted, [])
+
+ def test_default_branch_and_invalid_refs_are_rejected(self):
+ selectors = [dict(deleted_branch='main'), dict(deleted_branch=''),
+ dict(deleted_branch=42), dict(deleted_branch=True),
+ dict(deleted_branch='../main'), dict(deleted_branch='bad\nname'),
+ dict(pull_request=0), dict(pull_request=True), {},
+ dict(pull_request=17, deleted_branch='work')]
+ for selector in selectors:
+ with self.subTest(selector=selector):
+ client = FakeClient()
+ with self.assertRaises(ValueError):
+ pruner.prune(client, apply=True, **selector)
+ self.assertEqual(client.deleted, [])
+
+ def test_inventory_is_fully_validated_before_any_delete(self):
+ ref = 'refs/pull/17/merge'
+ invalid = [dict(id=102, ref='refs/heads/main', size_in_bytes=3),
+ dict(id=102, ref='refs/tags/v1.2.55_desktop', size_in_bytes=3),
+ dict(id=101, ref=ref, size_in_bytes=3),
+ dict(id=True, ref=ref, size_in_bytes=3),
+ dict(id=102, ref=ref, size_in_bytes=-1), None]
+ for row in invalid:
+ with self.subTest(row=row):
+ client = FakeClient(pages=[[dict(id=101, ref=ref, size_in_bytes=3), row]])
+ with self.assertRaises(ValueError):
+ pruner.prune(client, pull_request=17, apply=True)
+ self.assertEqual(client.deleted, [])
+
+ def test_pagination_keeps_the_same_exact_ref(self):
+ ref = 'refs/pull/17/merge'
+ rows = [dict(id=i, ref=ref, size_in_bytes=i) for i in range(1, 102)]
+ client = FakeClient(pages=[rows[:100], rows[100:]])
+ result = pruner.prune(client, pull_request=17, apply=True)
+ self.assertEqual(len(result['removed_ids']), 101)
+ self.assertEqual(result['removed_bytes'], sum(range(1, 102)))
+ self.assertEqual(len(client.deleted), 101)
+
+ def test_dry_run_has_no_mutations(self):
+ client = FakeClient()
+ result = pruner.prune(client, pull_request=17)
+ self.assertEqual(result['status'], 'ready')
+ self.assertEqual(result['selected_ids'], [101])
+ self.assertEqual(client.deleted, [])
+
+ def test_concurrent_eviction_is_idempotent(self):
+ client = FakeClient()
+ client.missing.add(101)
+ result = pruner.prune(client, pull_request=17, apply=True)
+ self.assertEqual(result['status'], 'passed')
+ self.assertEqual(result['removed_ids'], [])
+ self.assertEqual(result['removed_bytes'], 0)
+
+ def test_unknown_api_or_auth_failure_never_means_deleted_branch(self):
+ client = FakeClient(ref='refs/heads/work')
+ original = client.api
+ def fail(path='', method='GET'):
+ if path.startswith('git/ref/'):
+ raise RuntimeError('API unavailable')
+ return original(path, method)
+ client.api = fail
+ with self.assertRaises(RuntimeError):
+ pruner.prune(client, deleted_branch='work', apply=True)
+ self.assertEqual(client.deleted, [])
+
+ def test_client_distinguishes_missing_from_auth_failure_and_bounds_calls(self):
+ client = pruner.Client('owner/repo')
+ for status, error in [('404', pruner.NotFound), ('403', RuntimeError)]:
+ with patch.object(pruner.subprocess, 'run', return_value=SimpleNamespace(returncode=1, stdout='', stderr=f'gh: failed (HTTP {status})')) as run:
+ with self.assertRaises(error):
+ client.api('git/ref/heads/work')
+ self.assertLessEqual(run.call_args.kwargs['timeout'], 20)
+ with patch.object(pruner.subprocess, 'run', side_effect=subprocess.TimeoutExpired(['gh'], 20)):
+ with self.assertRaises(subprocess.TimeoutExpired):
+ client.api()
+
+ def test_wrong_repository_and_exhausted_budget_fail_closed(self):
+ client = FakeClient()
+ client.api = lambda *a, **k: dict(full_name='elsewhere/repo', default_branch='main')
+ with self.assertRaises(ValueError):
+ pruner.prune(client, pull_request=17, apply=True)
+ with patch.object(pruner.subprocess, 'run') as run:
+ with self.assertRaises(TimeoutError):
+ pruner.Client('owner/repo', budget=0).api()
+ run.assert_not_called()
+
+
+if __name__ == '__main__':
+ unittest.main()