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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Remove caches belonging to closed PRs and deleted branches (#658)
Dee16adcc7e4700
diff --git a/.github/workflows/cache-cleanup.yml b/.github/workflows/cache-cleanup.ymlnew file mode 100644index 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" --applydiff --git a/docs/validation-and-release.md b/docs/validation-and-release.mdindex 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 insteadof copying it into the runner's discarded local tool cache. Authentication stillruns 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 runWhen the final implementation is pushed, start `make release-desktop ARGS="--prepare"`diff --git a/scripts/prune-finished-caches.py b/scripts/prune-finished-caches.pynew file mode 100644index 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.pynew file mode 100644index 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()