Files
MobileGL/scripts/ci/release.py
T

379 lines
16 KiB
Python

#!/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
from collections import Counter
import hashlib
import json
import os
import re
import subprocess
import sys
import tempfile
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)
return 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):
representatives = {}
commit_counts = Counter()
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]):
identity = (name, email.casefold())
representatives.setdefault(identity, commit)
commit_counts[identity] += 1
linked = {}
for identity, commit in representatives.items():
author = github.request(f"/commits/{commit}").get("author") or {}
login = author.get("login", "")
if LOGIN.fullmatch(login):
linked[identity] = login
# An unlinked author name can match a login confirmed by another commit.
known_logins = {login.casefold(): login for login in linked.values()}
labels = {}
totals = Counter()
for identity, count in commit_counts.items():
name = " ".join(identity[0].split())
login = linked.get(identity) or known_logins.get(name.removeprefix("@").casefold())
escaped_name = "".join(f"\\{char}" if char in "\\@<>&*_[`]" else char
for char in name)
credit = f"@{login}" if login else escaped_name
if credit:
key = credit.casefold()
labels.setdefault(key, credit)
totals[key] += count
rows = []
for key in sorted(totals, key=lambda key: (-totals[key], key)):
count = totals[key]
unit = "commit" if count == 1 else "commits"
rows.append(f"- {labels[key]} — {count:,} {unit}")
return "\n".join(rows)
def download_plugin_apk(github, tag, commit, run_id, directory):
if not re.fullmatch(r"[0-9]+", run_id):
raise ReleaseError("The successful APK run ID is missing or invalid.")
run_path = f"/actions/runs/{run_id}"
run = github.request(run_path)
if (not eligible_run(run, github.repo, commit, tag)
or run["path"].split("@", 1)[0] != ".github/workflows/apk.yml"
or run["status"] != "completed" or run["conclusion"] != "success"):
raise ReleaseError("The APK run must be a successful validation of the tagged commit.")
name = f"MobileGL-plugin-release-{commit}.apk"
artifacts = [
entry for entry in github.pages(f"{run_path}/artifacts", [("name", name)], key="artifacts")
if entry["name"] == name and not entry["expired"]
]
if len(artifacts) != 1:
raise ReleaseError(f"Expected one unexpired {name} in APK run {run_id}.")
artifact = artifacts[0]
destination = directory / f"MobileGL-plugin-{tag}.apk"
with destination.open("wb") as output:
subprocess.run(["gh", "api", "--allow-escape-sequences",
f"repos/{github.repo}/actions/artifacts/{artifact['id']}/zip"],
stdout=output, check=True, timeout=120)
with destination.open("rb") as apk:
digest = "sha256:" + hashlib.file_digest(apk, "sha256").hexdigest()
if digest != artifact.get("digest"):
raise ReleaseError("The plugin APK does not match the digest from the APK run.")
print(f"Verified {destination.name} from APK run {run_id} ({digest}).", flush=True)
return destination
def publish(github, tag, tag_sha, commit, notes, sender, apk_run_id):
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```"])
with tempfile.TemporaryDirectory() as directory:
apk = download_plugin_apk(github, tag, commit, apk_run_id, Path(directory))
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.")
command = ["gh", "release", "create", tag, str(apk), "--repo", github.repo,
"--verify-tag", "--title", tag, "--notes-file", "-"]
if "-" in tag:
command.append("--prerelease")
# The release becomes public after its asset uploads successfully.
subprocess.run(command, input="\n\n".join(parts), text=True, check=True)
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):
runs = validate_workflows(github, commit, tag)
with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output:
print(f"apk_run_id={runs['apk.yml']['id']}", file=output)
else:
publish(github, tag, tag_sha, commit, notes, sender, os.environ.get("APK_RUN_ID", ""))
if __name__ == "__main__":
try:
main()
except (ReleaseError, OSError, subprocess.SubprocessError) as exc:
sys.exit(str(exc))