From 6306b28af5b01c30f32bfb89d590e382778aa247 Mon Sep 17 00:00:00 2001 From: BZLZHH Date: Sat, 21 Nov 2026 10:31:27 +0800 Subject: [PATCH] [CI, Docs] (.github/workflows, CONTRIBUTING.md, scripts/ci): validate and publish version tags --- .github/workflows/apk.yml | 7 +- .github/workflows/hygiene.yml | 4 +- .github/workflows/release.yml | 63 +++++++ .github/workflows/test.yml | 23 +-- CONTRIBUTING.md | 14 +- scripts/ci/release.py | 314 ++++++++++++++++++++++++++++++++++ 6 files changed, 408 insertions(+), 17 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 scripts/ci/release.py diff --git a/.github/workflows/apk.yml b/.github/workflows/apk.yml index fdd1b776..5f78d58a 100644 --- a/.github/workflows/apk.yml +++ b/.github/workflows/apk.yml @@ -1,4 +1,5 @@ name: MobileGL APK +run-name: ${{ (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main')) && format('Release validation ({0})', github.ref) || '' }} on: push: @@ -73,7 +74,7 @@ jobs: CCACHE_MAXSIZE: 1500M CCACHE_NOHASHDIR: "true" MOBILEGL_CMAKE_COMPILER_LAUNCHER: ccache - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} steps: - name: Checkout repo @@ -301,7 +302,7 @@ jobs: name: trace case matrix runs-on: ubuntu-26.04 env: - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} # How much replay one emulator job aims for, in seconds as the duration hints count them. # A (lane, transport, backend) cell is cut into as many shards as that takes, and its # cases are spread so the shards of a cell come out even (tools/trace_replay/trace_cases.py, @@ -795,7 +796,7 @@ jobs: actions: write contents: read env: - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} steps: - name: Checkout repo diff --git a/.github/workflows/hygiene.yml b/.github/workflows/hygiene.yml index 2431b351..94817620 100644 --- a/.github/workflows/hygiene.yml +++ b/.github/workflows/hygiene.yml @@ -18,8 +18,8 @@ jobs: runs-on: ubuntu-26.04 timeout-minutes: 15 env: - # A new branch is checked for the commits it adds to the default branch. - TEXT_HYGIENE_BASE_BRANCH: ${{ github.event.repository.default_branch }} + # A new branch is checked for the commits it adds to the development branch. + TEXT_HYGIENE_BASE_BRANCH: dev steps: - name: Checkout repo uses: actions/checkout@v6 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..8564b4f3 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,63 @@ +name: Release + +on: + push: + branches: [main] + tags: ['v*'] + workflow_dispatch: + +permissions: {} + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + validate: + if: ${{ github.event_name == 'push' && github.ref_type == 'tag' }} + runs-on: ubuntu-26.04 + timeout-minutes: 345 + permissions: + actions: write + contents: read + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + persist-credentials: false + - name: Require both workflows + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/ci/release.py validate + + publish: + needs: validate + runs-on: ubuntu-26.04 + timeout-minutes: 10 + permissions: + contents: write + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + persist-credentials: false + - name: Publish source release + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/ci/release.py publish + + preflight: + if: ${{ github.ref == 'refs/heads/main' && (github.event_name == 'workflow_dispatch' || github.event.created) }} + runs-on: ubuntu-26.04 + timeout-minutes: 345 + permissions: + actions: write + contents: write + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + - name: Exercise release permissions and validation + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/ci/release.py preflight diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 359f3208..52d44d2e 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,4 +1,5 @@ name: Test +run-name: ${{ (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main')) && format('Release validation ({0})', github.ref) || '' }} on: push: @@ -46,7 +47,7 @@ jobs: build-type: ${{ steps.configure.outputs.build-type }} env: BUILD_DIR: build-linux - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} CCACHE_BASEDIR: ${{ github.workspace }} CCACHE_COMPRESS: "true" CCACHE_DIR: ${{ github.workspace }}/.ccache @@ -389,7 +390,7 @@ jobs: # Initialize()'s glslang table prewarm. The retrace legs keep it: they replay real apps. env: MOBILEGL_DISABLE_SHADER_PREWARM: "1" - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} steps: - name: Checkout repo @@ -471,7 +472,7 @@ jobs: strategy: fail-fast: false matrix: - include: ${{ fromJSON((github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && '[{"lane":"monolith-control","transport":"monolith"},{"lane":"inproc-acceptance","transport":"inproc"}]' || '[{"lane":"monolith-control","transport":"monolith"}]') }} + include: ${{ fromJSON((github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && '[{"lane":"monolith-control","transport":"monolith"},{"lane":"inproc-acceptance","transport":"inproc"}]' || '[{"lane":"monolith-control","transport":"monolith"}]') }} env: # Short-lived test processes skip the glslang prewarm, as in the test job. MOBILEGL_DISABLE_SHADER_PREWARM: "1" @@ -479,7 +480,7 @@ jobs: MOBILEGL_IPC_ROLE_SPLIT_STATE: "1" MOBILEGL_IPC_STRICT_ERRORS: "1" MOBILEGL_IPC_RUN_AHEAD: "1" - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} steps: - name: Checkout repo @@ -1169,7 +1170,7 @@ jobs: name: build guard (split reuse) runs-on: ubuntu-26.04 timeout-minutes: 150 - if: ${{ github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' }} + if: ${{ github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main')) }} # Consumers read only its outputs, and any verdict but 'identical' (none at all included) # keeps both builds. continue-on-error: true @@ -1178,7 +1179,7 @@ jobs: image: ${{ steps.guard.outputs.image }} compiler: ${{ steps.guard.outputs.compiler }} env: - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} # Every step may fail without failing the job: a setup step that failed leaves a configure # that fails, which the guard reports as 'unknown'. @@ -1550,7 +1551,7 @@ jobs: SPLIT_REUSE: ${{ needs.build-guard.outputs.verdict == 'identical' && 'true' || 'false' }} SPLIT_BUILD_DIR: ${{ needs.build-guard.outputs.verdict == 'identical' && 'build-linux' || 'build-split' }} SPLIT_RUNTIME: ${{ needs.build-guard.outputs.verdict == 'identical' && 'mobilegl-linux-runtime' || 'mobilegl-linux-runtime-split' }} - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} steps: - name: Checkout repo @@ -1895,7 +1896,7 @@ jobs: SPLIT_REUSE: ${{ needs.build-guard.outputs.verdict == 'identical' && 'true' || 'false' }} SPLIT_BUILD_DIR: ${{ needs.build-guard.outputs.verdict == 'identical' && 'build-linux' || 'build-split' }} SPLIT_RUNTIME: ${{ needs.build-guard.outputs.verdict == 'identical' && 'mobilegl-linux-runtime' || 'mobilegl-linux-runtime-split' }} - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} steps: - name: Checkout repo @@ -2800,7 +2801,7 @@ jobs: name: trace case matrix runs-on: ubuntu-26.04 env: - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} # How many jobs replay one (lane, transport, backend) cell of the Linux retrace lanes. Each # job replays its share of the cell's cases one after another; a cell with little to # replay gets fewer jobs (tools/trace_replay/trace_cases.py, shard_matrix). @@ -3125,7 +3126,7 @@ jobs: actions: write contents: read env: - MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && 'ON' || 'OFF' }} + MOBILEGL_CI_DISAGGREGATED: ${{ (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && 'ON' || 'OFF' }} steps: - name: Checkout repo @@ -3574,7 +3575,7 @@ jobs: - build-linux-monolith-control - build-retrace - trace-cases - if: ${{ !cancelled() && (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup') && needs.build-linux-monolith-control.result == 'success' && needs.build-retrace.result == 'success' && needs.trace-cases.result == 'success' }} + if: ${{ !cancelled() && (github.ref_name == 'dev' || github.ref_name == 'feat/disaggregated' || github.ref_name == 'codex/fix-github-ci' || github.ref_name == 'cleanup' || (github.event_name == 'workflow_dispatch' && (github.ref_type == 'tag' || github.ref == 'refs/heads/main'))) && needs.build-linux-monolith-control.result == 'success' && needs.build-retrace.result == 'success' && needs.trace-cases.result == 'success' }} strategy: fail-fast: false matrix: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3450e760..d0068b67 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,7 +81,7 @@ Example: ## Checks -`python3 scripts/check_text_hygiene.py ci` runs what CI runs. It checks the commits on the branch's own line of history since the check was added. A push that moves a branch forward checks the commits it adds. A new branch, a force push and a run that is not a push check the commits the branch adds to the base branch, which is the repository's default branch `dev` (CI reads it from the event). Set `TEXT_HYGIENE_BASE_BRANCH` to compare with another branch. Another branch that adds nothing to the base branch has only its tree checked, and the base branch at its own tip checks its last commit. +`python3 scripts/check_text_hygiene.py ci` runs what CI runs. It checks the commits on the branch's own line of history since the check was added. A push that moves a branch forward checks the commits it adds. A new branch, a force push and a run that is not a push check the commits the branch adds to the base branch, which is the development branch `dev`. Set `TEXT_HYGIENE_BASE_BRANCH` to compare with another branch. Another branch that adds nothing to the base branch has only its tree checked, and the base branch at its own tip checks its last commit. These fail on any violation: @@ -112,3 +112,15 @@ These are ratchets: each total may only go down. `python3 scripts/check_structure.py report` lists what each total counts, and `tree --update-baseline` lowers the baseline the same way. Not checked by CI: the platform, switch and lifetime-id rules, planning ids outside comments, English outside comments, and the regeneration step for generated code. + +## Releases + +Fast-forward main to the selected dev commit. Create an annotated version tag at +that commit, with the release notes as the tag message. Push main before pushing +the tag. Use v26.11 for a stable release, or a suffix such as -alpha.1 or -rc.1 +for a prerelease. + +The Release workflow requires Test and MobileGL APK to succeed at the tagged +commit. It reuses matching runs and dispatches missing ones. After reviewing +the linked runs in its summary, rerun a failed validation before retrying +Release. Use a new tag if a fix changes the release commit. diff --git a/scripts/ci/release.py b/scripts/ci/release.py new file mode 100644 index 00000000..8914ccef --- /dev/null +++ b/scripts/ci/release.py @@ -0,0 +1,314 @@ +#!/usr/bin/env python3 +# MobileGL - scripts/ci/release.py +# Copyright (c) 2025-2026 MobileGL-Dev +# Licensed under the GNU Lesser General Public License v3.0: +# https://www.gnu.org/licenses/gpl-3.0.txt +# https://www.gnu.org/licenses/lgpl-3.0.txt +# SPDX-License-Identifier: LGPL-3.0-only +# End of Source File Header + +"""Validate and publish an annotated version tag after both required workflows succeed.""" + +import argparse +import json +import os +import re +import subprocess +import sys +import time +from pathlib import Path +from urllib.error import HTTPError, URLError +from urllib.parse import quote, urlencode +from urllib.request import Request, urlopen + + +WORKFLOWS = {"test.yml": "Test", "apk.yml": "MobileGL APK"} +WAIT_SECONDS = 330 * 60 +POLL_SECONDS = 30 +VERSION = re.compile(r"v[0-9]+\.[0-9]+(?:-(?:alpha|rc)\.[1-9][0-9]*)?") +SHA = re.compile(r"[0-9a-f]{40}") +LOGIN = re.compile(r"[a-zA-Z0-9][a-zA-Z0-9-]*(?:\[bot\])?") + + +class ReleaseError(Exception): + pass + + +class GitHub: + def __init__(self): + self.repo = os.environ["GITHUB_REPOSITORY"] + self.url = f"{os.environ['GITHUB_SERVER_URL']}/{self.repo}" + self.api = f"{os.environ['GITHUB_API_URL']}/repos/{self.repo}" + self.headers = { + "Authorization": f"Bearer {os.environ['GH_TOKEN']}", + "Accept": "application/vnd.github+json", + "Content-Type": "application/json", + "X-GitHub-Api-Version": "2026-03-10", + } + + def request(self, path, method="GET", body=None, *, deadline=None, allow_missing=False): + data = json.dumps(body).encode() if body is not None else None + request = Request(self.api + path, data=data, headers=self.headers, method=method) + for attempt in range(3): + remaining = deadline - time.monotonic() if deadline is not None else 20 + if remaining <= 0: + raise ReleaseError("The 330-minute validation deadline elapsed.") + try: + with urlopen(request, timeout=min(20, remaining)) as response: + raw = response.read() + return json.loads(raw) if raw else None + except HTTPError as exc: + if exc.code == 404 and allow_missing: + return None + if method != "GET" or exc.code not in {429, 500, 502, 503, 504} or attempt == 2: + raise ReleaseError(f"{method} {path} returned HTTP {exc.code}: " + f"{exc.read().decode(errors='replace')}") from exc + except (URLError, TimeoutError): + if method != "GET" or attempt == 2: + raise + time.sleep(min(2 ** attempt, remaining)) + + def pages(self, path, params=(), key=None, deadline=None): + for page in range(1, 1001): + query = urlencode([*params, ("per_page", 100), ("page", page)]) + response = self.request(f"{path}?{query}", deadline=deadline) + entries = response[key] if key else response + yield from entries + if len(entries) < 100: + return + raise ReleaseError(f"Too many result pages for {path}.") + + def tag_object(self, tag): + ref = self.request(f"/git/ref/tags/{quote(tag, safe='')}", allow_missing=True) + return ref["object"] if ref else None + + def release_for_tag(self, tag): + return self.request(f"/releases/tags/{quote(tag, safe='')}", allow_missing=True) + + def dispatch(self, workflow, ref, deadline): + response = self.request(f"/actions/workflows/{workflow}/dispatches", "POST", + {"ref": ref}, deadline=deadline) + if not isinstance(response, dict) or not response.get("workflow_run_id"): + raise ReleaseError(f"The dispatch for {workflow} did not return a run ID.") + return response["workflow_run_id"] + + def create_release(self, tag, commit, body, draft=False): + return self.request("/releases", "POST", { + "tag_name": tag, + "target_commitish": commit, + "name": tag, + "body": body, + "draft": draft, + "prerelease": "-" in tag, + "generate_release_notes": False, + }) + + +def git(*args): + return subprocess.check_output(["git", *args]).decode("utf-8") + + +def ancestor_of(commit, ref): + return subprocess.run(["git", "merge-base", "--is-ancestor", commit, ref], + check=False).returncode == 0 + + +def event_candidate(github): + event = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text()) + tag = os.environ["GITHUB_REF_NAME"] + if not VERSION.fullmatch(tag): + raise ReleaseError(f"Unsupported version tag {tag!r}.") + if event.get("deleted") or event.get("forced") or not event.get("created"): + raise ReleaseError("Release requires a newly created version tag.") + ref = f"refs/tags/{tag}" + tag_sha = git("rev-parse", "--verify", ref).strip() + if git("cat-file", "-t", tag_sha).strip() != "tag": + raise ReleaseError("Release requires an annotated tag.") + commit = git("rev-parse", "--verify", f"{ref}^{{commit}}").strip() + if git("rev-parse", "--verify", "HEAD").strip() != commit: + raise ReleaseError("The checkout differs from the tagged commit.") + if event.get("after") not in {tag_sha, commit} or event.get("ref") != ref: + raise ReleaseError("The tag differs from the original push event.") + if not ancestor_of(commit, "refs/remotes/origin/main"): + raise ReleaseError("The tagged commit must be reachable from upstream main.") + remote_tag = github.tag_object(tag) + if not remote_tag or remote_tag["type"] != "tag" or remote_tag["sha"] != tag_sha: + raise ReleaseError("The remote annotated tag differs from the checkout.") + # Read the tag object's message so paragraph breaks and signed tags are handled by Git. + notes = git("for-each-ref", "--format=%(contents)", ref).rstrip("\n") + signature = git("for-each-ref", "--format=%(contents:signature)", ref).strip() + if signature and notes.endswith(signature): + notes = notes.removesuffix(signature).rstrip("\n") + if not notes.strip(): + raise ReleaseError("The annotated tag must contain release notes.") + sender = event.get("sender", {}).get("login", "") + if not LOGIN.fullmatch(sender): + raise ReleaseError("The tag push event does not identify a GitHub account.") + return tag, tag_sha, commit, notes, sender + + +def release_already_exists(github, tag): + release = github.release_for_tag(tag) + if release and release["draft"]: + raise ReleaseError(f"A draft Release already exists for {tag}.") + if release: + print(f"Release already published: {release['html_url']}") + return bool(release) + + +def eligible_run(run, repo, commit, tag): + if run["head_sha"] != commit or (run.get("head_repository") or {}).get("full_name") != repo: + return False + if run["event"] == "push": + return run["head_branch"] == "dev" + return run["event"] == "workflow_dispatch" and run["display_title"] in { + f"Release validation (refs/tags/{tag})", + "Release validation (refs/heads/main)", + } + + +def latest_run(github, workflow, commit, tag, deadline): + runs = github.pages(f"/actions/workflows/{workflow}/runs", + [("head_sha", commit)], key="workflow_runs", deadline=deadline) + return next((run for run in runs if eligible_run(run, github.repo, commit, tag)), None) + + +def summarize(github, runs): + with Path(os.environ["GITHUB_STEP_SUMMARY"]).open("a") as summary: + summary.write("### Release validation\n\n") + for workflow, run in runs.items(): + name = WORKFLOWS[workflow] + status = run.get("conclusion") or run.get("status") or "dispatched" + url = f"{github.url}/actions/runs/{run['id']}" + summary.write(f"- [{name}]({url}) — {status}\n") + + +def wait_for_runs(github, runs, commit, deadline): + while True: + all_success = True + for workflow, run in runs.items(): + if run.get("conclusion") == "success": + continue + run = github.request(f"/actions/runs/{run['id']}", deadline=deadline) + runs[workflow] = run + if run["head_sha"] != commit or (run.get("head_repository") or {}).get("full_name") != github.repo: + raise ReleaseError(f"{WORKFLOWS[workflow]} ran against an unexpected repository or commit.") + if run["status"] == "completed" and run["conclusion"] != "success": + raise ReleaseError(f"{WORKFLOWS[workflow]} concluded {run['conclusion']}.") + all_success &= run["conclusion"] == "success" + if all_success: + return + remaining = deadline - time.monotonic() + if remaining <= 0: + raise ReleaseError("The 330-minute validation deadline elapsed.") + time.sleep(min(POLL_SECONDS, remaining)) + + +def validate_workflows(github, commit, tag=None): + deadline = time.monotonic() + WAIT_SECONDS + runs = {} + try: + if tag: + for workflow in WORKFLOWS: + run = latest_run(github, workflow, commit, tag, deadline) + if run: + runs[workflow] = run + for workflow, run in runs.items(): + if run["status"] == "completed" and run["conclusion"] != "success": + raise ReleaseError(f"{WORKFLOWS[workflow]} concluded {run['conclusion']}.") + for workflow, name in WORKFLOWS.items(): + if workflow not in runs: + runs[workflow] = {"id": github.dispatch(workflow, tag or "main", deadline)} + print(f"{name}: {github.url}/actions/runs/{runs[workflow]['id']}", flush=True) + wait_for_runs(github, runs, commit, deadline) + finally: + summarize(github, runs) + + +def previous_release(github, tag, commit): + for release in github.pages("/releases"): + previous = release["tag_name"] + if release["draft"] or previous == tag or not VERSION.fullmatch(previous): + continue + ref = f"refs/tags/{previous}" + if ancestor_of(f"{ref}^{{commit}}", commit): + return previous + return None + + +def contributors(github, revision): + authors = {} + data = git("log", "-z", "--format=%H%x00%aN%x00%aE", revision) + fields = data.split("\0") + for commit, name, email in zip(fields[::3], fields[1::3], fields[2::3]): + authors.setdefault((name, email.casefold()), commit) + credits = {} + for (name, _email), commit in authors.items(): + author = github.request(f"/commits/{commit}").get("author") or {} + login = author.get("login", "") + escaped_name = "".join(f"\\{char}" if char in "\\@<>&*_[`]" else char + for char in " ".join(name.split())) + credit = f"@{login}" if LOGIN.fullmatch(login) else escaped_name + if credit: + credits.setdefault(credit.casefold(), credit) + return ", ".join(sorted(credits.values(), key=str.casefold)) + + +def publish(github, tag, tag_sha, commit, notes, sender): + if release_already_exists(github, tag): + return + previous = previous_release(github, tag, commit) + revision = f"refs/tags/{previous}..{commit}" if previous else commit + credits = contributors(github, revision) + history = (f"[Compare {previous} to {tag}]({github.url}/compare/{previous}...{tag})" + if previous else f"[Commit history for {tag}]({github.url}/commits/{tag})") + parts = [notes, f"Released by @{sender}"] + if credits: + parts.append(f"**Contributors**\n\n{credits}") + parts.extend([history, "Clone with submodules:\n\n" + f"```sh\ngit clone --branch {tag} --recurse-submodules {github.url}.git\n```"]) + remote_tag = github.tag_object(tag) + if not remote_tag or remote_tag["sha"] != tag_sha: + raise ReleaseError("The remote tag changed while preparing the release.") + release = github.create_release(tag, commit, "\n\n".join(parts)) + print(f"Published {release['html_url']}") + + +def preflight(github): + commit = os.environ["GITHUB_SHA"] + if os.environ["GITHUB_REF"] != "refs/heads/main" or not SHA.fullmatch(commit): + raise ReleaseError("Release preflight must run on main.") + tag = f"release-preflight-{os.environ['GITHUB_RUN_ID']}-{os.environ['GITHUB_RUN_ATTEMPT']}" + if github.tag_object(tag): + raise ReleaseError("The preflight name is already a Git tag.") + draft = github.create_release(tag, commit, "Verifies release permissions.", draft=True) + if not draft["draft"]: + raise ReleaseError("The preflight Release is not a draft.") + github.request(f"/releases/{draft['id']}", "DELETE") + if github.tag_object(tag): + raise ReleaseError("Preflight unexpectedly created a Git tag.") + print("Draft Release creation and cleanup succeeded.", flush=True) + validate_workflows(github, commit) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("command", choices=("validate", "publish", "preflight")) + command = parser.parse_args().command + github = GitHub() + if command == "preflight": + preflight(github) + return + tag, tag_sha, commit, notes, sender = event_candidate(github) + if command == "validate": + if not release_already_exists(github, tag): + validate_workflows(github, commit, tag) + else: + publish(github, tag, tag_sha, commit, notes, sender) + + +if __name__ == "__main__": + try: + main() + except (ReleaseError, OSError, subprocess.CalledProcessError) as exc: + sys.exit(str(exc))