From e29e01b4503528a9f53328b79bb8807369934a00 Mon Sep 17 00:00:00 2001 From: albert Date: Sun, 1 Nov 2026 00:27:06 -0700 Subject: [PATCH] Resume verified releases through draft-aware controller recovery --- .github/workflows/release.yml | 6 ++- docs/development/releasing.md | 13 ++++++ qualification/release/test_release.py | 62 +++++++++++++++++++++++++ scripts/publish-release.py | 65 +++++++++++++++++++++------ 4 files changed, 131 insertions(+), 15 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0d69569..9d1c9e9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -60,6 +60,7 @@ jobs: - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0 with: persist-credentials: false + fetch-depth: 0 - name: Validate dispatch and release tooling env: RELEASE_SHA: ${{ inputs.source_sha }} @@ -68,13 +69,16 @@ jobs: RELEASE_PHASE: ${{ inputs.phase }} RELEASE_CANDIDATE_VERSION: ${{ inputs.candidate_version }} run: | - test "$RELEASE_SHA" = "$GITHUB_SHA" [[ "$RELEASE_SHA" =~ ^[0-9a-f]{40}$ ]] + test "$(git rev-parse HEAD)" = "$GITHUB_SHA" [[ "$RELEASE_RUN" =~ ^[0-9]+$ ]] [[ -z "$RELEASE_STAGE_RUN" || "$RELEASE_STAGE_RUN" =~ ^[0-9]+$ ]] if [[ "$RELEASE_PHASE" == stage ]]; then + test "$RELEASE_SHA" = "$GITHUB_SHA" [[ "$RELEASE_CANDIDATE_VERSION" =~ ^0[.]0[.]1-rc[.][1-9][0-9]*$ ]] (( ${#RELEASE_CANDIDATE_VERSION} <= 128 )) + else + git merge-base --is-ancestor "$RELEASE_SHA" HEAD fi python3 -m unittest discover -s qualification/release -p 'test_*.py' - name: Install isolated official release-attestation CLI diff --git a/docs/development/releasing.md b/docs/development/releasing.md index 09cee3b..e98926c 100644 --- a/docs/development/releasing.md +++ b/docs/development/releasing.md @@ -161,6 +161,19 @@ configuration examples, full HTTPS root/subpath proxy examples and operations. ## Safe retries and public verification +The published-release-by-tag API does not return drafts. The controller discovers +drafts through the authenticated release list, then checks their assets by release +ID. A retry reuses the matching draft and uploads only missing assets. + +Once the version tag or image exists, keep its qualified software commit frozen. +A controller-only fix can be merged through the release branch and resume +publication from trusted `main` without moving that tag or rebuilding its image. +For `publish`, the selected software SHA must be an ancestor of the current main +controller and still match the exact successful verification run, candidate and +staging evidence. Client/runtime receipts and release notes are read from that +selected commit. The operation journal records controller and software commits +separately. Staging continues to require the current verified main SHA. + There is no transaction across GHCR, Git refs and Releases. Each irreversible step appends an operation to the retained `release-operations-RUN-ATTEMPT` journal. Inspect logs and actual state with `gh run view --log-failed`, `gh api`, diff --git a/qualification/release/test_release.py b/qualification/release/test_release.py index f8c4e24..1c9d031 100644 --- a/qualification/release/test_release.py +++ b/qualification/release/test_release.py @@ -35,6 +35,68 @@ def setUp(self): def test_correct_run_passes(self): publish.verification(self.run, self.jobs, SHA) + def test_release_lookup_finds_drafts_and_handles_pagination(self): + from unittest.mock import patch + draft = {'id': 123, 'tag_name': 'v0.0.1', 'draft': True, 'assets': []} + published = [{'id': index, 'tag_name': 'v9.' + str(index), 'draft': False} for index in range(100)] + with patch.object(publish, 'api', side_effect=[published, [draft]]) as api: + self.assertEqual(publish.release_for_tag(), draft) + self.assertEqual(api.call_count, 2) + with patch.object(publish, 'api', return_value=[]): + self.assertIsNone(publish.release_for_tag()) + with patch.object(publish, 'api', return_value=[draft, draft | {'id': 124}]), self.assertRaises(AssertionError): + publish.release_for_tag() + + def test_controller_can_resume_frozen_source_without_changing_its_inputs(self): + import hashlib + import subprocess + from unittest.mock import patch + with tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) + def git(*arguments): + return subprocess.check_output(['git', '-C', str(root), '-c', 'user.name=Release fixture', + '-c', 'user.email=release-fixture@example.invalid', '-c', 'commit.gpgsign=false', *arguments], text=True).strip() + git('init', '--quiet', '--initial-branch=main') + for name in ('Dockerfile', 'compose.yaml'): + (root / name).write_text('qualified runtime input\n') + notes = root / 'docs/releases/0.0.1.md' + notes.parent.mkdir(parents=True) + notes.write_text('Qualified release notes. [Operations](../operations.md)\n') + jar = '7' * 64 + receipt = {'status': 'passed', 'jarSha256': jar, + 'runtimeInputs': {name: hashlib.sha256((root / name).read_bytes()).hexdigest() for name in ('Dockerfile', 'compose.yaml')}, + 'baselineReplacement': {'status': 'passed', 'correctedJarSha256': jar}, + 'clients': {name: {'status': 'passed'} for name in ('thunderbird-system-vancouver', 'thunderbird-explicit-vancouver', 'thunderbird-explicit-berlin', 'gnome-vancouver')}} + receipt_path = root / 'qualification/evidence/releases/0.0.1/official-dependencies/verification.json' + receipt_path.parent.mkdir(parents=True) + candidate.write_json(receipt_path, receipt) + git('add', '.') + git('commit', '--quiet', '-m', 'Qualified source fixture') + source = git('rev-parse', 'HEAD') + (root / 'Dockerfile').write_text('later controller checkout input\n') + notes.write_text('Later checkout notes.\n') + git('add', '.') + git('commit', '--quiet', '-m', 'Later controller fixture') + controller = git('rev-parse', 'HEAD') + with patch.object(publish, 'ROOT', root): + publish.verify_source(source, controller, 'publish') + publish.verify_source(controller, controller, 'stage') + with self.assertRaises(AssertionError): + publish.verify_source(source, controller, 'stage') + with self.assertRaises(AssertionError): + publish.verify_source('f' * 40, controller, 'publish') + with self.assertRaises(AssertionError): + publish.verify_source(source, '0' * 40, 'publish') + publish.check_client_receipt(jar, source) + with self.assertRaises(AssertionError): + publish.check_client_receipt(jar) + self.assertEqual(publish.source_bytes(source, 'Dockerfile'), b'qualified runtime input\n') + selected_notes = publish.release_notes(source, from_git=True) + self.assertIn('Qualified release notes.', selected_notes) + self.assertNotIn('Later checkout notes.', selected_notes) + self.assertIn('/blob/' + source + '/docs/operations.md', selected_notes) + self.assertEqual(git('rev-parse', 'HEAD'), controller) + def test_wrong_sha_failed_incomplete_and_untrusted_runs_reject(self): for key, value in [('head_sha', 'b' * 40), ('status', 'in_progress'), ('conclusion', 'failure'), ('path', '.github/workflows/other.yml'), ('head_branch', 'fork'), ('event', 'pull_request')]: diff --git a/scripts/publish-release.py b/scripts/publish-release.py index 7556d4e..10b5c22 100644 --- a/scripts/publish-release.py +++ b/scripts/publish-release.py @@ -2,6 +2,7 @@ """Explicit tested-artifact promotion. Stage first; publish only the verified staged assets.""" import argparse import base64 +import hashlib import importlib.util import json import os @@ -46,6 +47,37 @@ def api(path, missing=False, method='GET', fields=None): return json.loads(result.stdout) if result.stdout else None +def release_for_tag(tag='v0.0.1'): + # The by-tag endpoint returns published releases only. Listings include drafts + # for this job's contents:write token, allowing interrupted uploads to resume. + matches = [] + page = 1 + while True: + releases = api(f'repos/{REPO}/releases?per_page=100&page={page}') + matches.extend(release for release in releases if release['tag_name'] == tag) + if len(releases) < 100: + break + page += 1 + assert len(matches) <= 1, 'Ambiguous release tag' + return matches[0] if matches else None + + +def verify_source(source_sha, controller_sha, phase): + assert phase in ('stage', 'publish'), 'Invalid release phase' + assert re.fullmatch(r'[0-9a-f]{40}', source_sha), 'Invalid source SHA' + head = command('git', '-C', str(ROOT), 'rev-parse', 'HEAD') + assert head == controller_sha, 'Dispatch/controller mismatch' + if phase == 'stage': + assert source_sha == head, 'Staging requires the current verified main commit' + else: + ancestry = subprocess.run(['git', '-C', str(ROOT), 'merge-base', '--is-ancestor', source_sha, head], capture_output=True) + assert ancestry.returncode == 0, 'Release source must belong to trusted main history' + + +def source_bytes(sha, filename): + return subprocess.check_output(['git', '-C', str(ROOT), 'show', f'{sha}:{filename}']) + + def verification(run, jobs, sha): assert run['repository']['full_name'] == REPO and run['head_repository']['full_name'] == REPO, 'Wrong repository' assert run['path'] == '.github/workflows/ci.yml' and run['name'] == 'verify', 'Wrong verification workflow' @@ -127,8 +159,8 @@ def candidate_version(version, value): return value -def release_notes(sha): - notes = (ROOT / 'docs/releases/0.0.1.md').read_text() +def release_notes(sha, from_git=False): + notes = source_bytes(sha, 'docs/releases/0.0.1.md').decode() if from_git else (ROOT / 'docs/releases/0.0.1.md').read_text() def source_link(match): path = posixpath.normpath('docs/releases/' + match.group(1)) assert not path.startswith('../'), 'Release documentation link escapes repository' @@ -150,7 +182,7 @@ def check_release(sha, digest=None): if target['type'] == 'tag': target = api(f'repos/{REPO}/git/tags/{target["sha"]}')['object'] assert target['type'] == 'commit' and target['sha'] == sha, 'Conflicting tag' - release = api(f'repos/{REPO}/releases/tags/v0.0.1', missing=True) + release = release_for_tag() if release: assert tag, 'Release without exact tag' if not release['draft']: @@ -158,11 +190,12 @@ def check_release(sha, digest=None): return tag, release -def check_client_receipt(jar_sha): - path = ROOT / 'qualification/evidence/releases/0.0.1/official-dependencies/verification.json' - receipt = json.loads(path.read_text()) +def check_client_receipt(jar_sha, source_sha=None): + def contents(name): + return source_bytes(source_sha, name) if source_sha else (ROOT / name).read_bytes() + receipt = json.loads(contents('qualification/evidence/releases/0.0.1/official-dependencies/verification.json')) assert receipt['jarSha256'] == jar_sha, 'Client qualification belongs to another executable' - assert receipt['runtimeInputs'] == {name: candidate.sha256(ROOT / name) for name in ('Dockerfile', 'compose.yaml')}, 'Client qualification runtime inputs changed' + assert receipt['runtimeInputs'] == {name: hashlib.sha256(contents(name)).hexdigest() for name in ('Dockerfile', 'compose.yaml')}, 'Client qualification runtime inputs changed' assert receipt['status'] == 'passed' assert receipt['baselineReplacement']['status'] == 'passed' and receipt['baselineReplacement']['correctedJarSha256'] == jar_sha, 'Internal baseline replacement not qualified' assert set(receipt['clients']) == {'thunderbird-system-vancouver', 'thunderbird-explicit-vancouver', 'thunderbird-explicit-berlin', 'gnome-vancouver'} @@ -183,17 +216,18 @@ def main(): staging = candidate_version(args.version, args.candidate_version) if args.phase == 'stage' else None assert os.environ['GITHUB_REPOSITORY'] == REPO assert os.environ['GITHUB_REF'] == 'refs/heads/main', 'Dispatch publication from main' - assert args.source_sha == os.environ['GITHUB_SHA'] == command('git', 'rev-parse', 'HEAD'), 'Dispatch/source mismatch' + verify_source(args.source_sha, os.environ['GITHUB_SHA'], args.phase) work = Path(args.work) work.mkdir(parents=True, exist_ok=False) log = work / 'operations.jsonl' + journal(log, 'controller-and-release-source', {'controllerCommit': os.environ['GITHUB_SHA'], 'sourceCommit': args.source_sha}) run = verify_run(args.verification_run, args.source_sha) artifact_name = f'verified-candidate-{run["id"]}-{run["run_attempt"]}' source = work / 'candidate' download(run['id'], artifact_name, source) record = candidate.validate(source) assert record['ciRun'] == run['id'] and record['ciAttempt'] == run['run_attempt'] and record['sourceCommit'] == args.source_sha - check_client_receipt(record['files']['caldav-server-0.0.1.jar']) + check_client_receipt(record['files']['caldav-server-0.0.1.jar'], args.source_sha) check_release(args.source_sha) subprocess.run(['docker', 'image', 'load', '--input', str(source / 'container.tar.gz')], check=True) config = json.loads(command('docker', 'image', 'inspect', record['imageId']))[0] @@ -267,9 +301,11 @@ def main(): journal(log, 'version-image-created-or-matched', {'digest': digest}) if not release: notes = work / 'release-notes.md' - notes.write_text(release_notes(args.source_sha)) + notes.write_text(release_notes(args.source_sha, from_git=True)) subprocess.run(['gh', 'release', 'create', 'v0.0.1', '--repo', REPO, '--verify-tag', '--draft', '--title', 'BusyStack CalDAV Server 0.0.1', '--notes-file', str(notes)], check=True) - release = api(f'repos/{REPO}/releases/tags/v0.0.1') + release = release_for_tag() + assert release, 'Created draft release is not visible' + journal(log, 'release-created-or-matched', {'releaseId': release['id'], 'draft': release['draft'], 'tag': release['tag_name']}) expected = stage['assets'] existing = {asset['name']: asset for asset in release['assets']} assert set(existing) <= set(expected), 'Unexpected release asset' @@ -278,13 +314,14 @@ def main(): if release['draft']: for name in sorted(set(expected) - set(existing)): subprocess.run(['gh', 'release', 'upload', 'v0.0.1', str(payload / name), '--repo', REPO], check=True) - remote = api(f'repos/{REPO}/releases/tags/v0.0.1') + remote = api(f'repos/{REPO}/releases/{release["id"]}') + assert remote['tag_name'] == 'v0.0.1', 'Release tag changed during publication' assert {asset['name']: asset.get('digest') for asset in remote['assets']} == {name: 'sha256:' + sha for name, sha in expected.items()} journal(log, 'draft-assets-verified', {'assets': expected}) if remote['draft']: subprocess.run(['gh', 'release', 'edit', 'v0.0.1', '--repo', REPO, '--draft=false', '--latest'], check=True) - published = api(f'repos/{REPO}/releases/tags/v0.0.1') - assert published['immutable'] and not published['draft'] + published = api(f'repos/{REPO}/releases/{release["id"]}') + assert published['tag_name'] == 'v0.0.1' and published['immutable'] and not published['draft'] journal(log, 'immutable-release-published', {'url': published['html_url'], 'digest': digest}) attestation = json.loads(command('gh', 'release', 'verify', 'v0.0.1', '--repo', REPO, '--format', 'json')) candidate.write_json(work / 'release-attestation.json', attestation)