Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
Expand All @@ -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
Expand Down
13 changes: 13 additions & 0 deletions docs/development/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down
62 changes: 62 additions & 0 deletions qualification/release/test_release.py
Original file line number Diff line number Diff line change
Expand Up @@ -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')]:
Expand Down
65 changes: 51 additions & 14 deletions scripts/publish-release.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand All @@ -150,19 +182,20 @@ 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']:
assert release.get('immutable') is True, 'Existing release is not immutable'
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'}
Expand All @@ -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]
Expand Down Expand Up @@ -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'
Expand All @@ -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)
Expand Down
Loading