Harden release workflow checks (#18)

bhack · web-flow · commit 69ed1ca3c0e7 · 2026-05-09T18:10:06.000+02:00
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -51,8 +51,57 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  validate-inputs:
+    name: Validate release inputs
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.target }}
+
+      - name: Validate dispatch inputs
+        env:
+          CREATE_GITHUB_RELEASE: ${{ inputs.create_github_release }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          PUBLISH_PYPI: ${{ inputs.publish_pypi }}
+          PUBLISH_TESTPYPI: ${{ inputs.publish_testpypi }}
+          TAG_NAME: ${{ inputs.tag_name }}
+        run: |
+          set -euo pipefail
+
+          project_version="$(
+            python3 -c 'from pathlib import Path; import tomllib; print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])'
+          )"
+          expected_tag="v${project_version}"
+
+          needs_tag=false
+          if [ "$CREATE_GITHUB_RELEASE" = "true" ] || [ "$PUBLISH_TESTPYPI" = "true" ] || [ "$PUBLISH_PYPI" = "true" ]; then
+            needs_tag=true
+          fi
+
+          if [ "$needs_tag" = "true" ] && [ -z "$TAG_NAME" ]; then
+            echo "::error::tag_name is required when creating a release or publishing to a package index"
+            exit 1
+          fi
+
+          if [ -n "$TAG_NAME" ] && [ "$TAG_NAME" != "$expected_tag" ]; then
+            echo "::error::tag_name must be ${expected_tag} for pyproject version ${project_version}"
+            exit 1
+          fi
+
+          if [ "$DRY_RUN" = "true" ] && { [ "$CREATE_GITHUB_RELEASE" = "true" ] || [ "$PUBLISH_TESTPYPI" = "true" ] || [ "$PUBLISH_PYPI" = "true" ]; }; then
+            echo "::warning::dry_run=true prevents release creation and package publishing jobs from running"
+          fi
+
+          if [ "$PUBLISH_PYPI" = "true" ] && [ "$CREATE_GITHUB_RELEASE" != "true" ]; then
+            echo "::warning::publishing PyPI without creating the GitHub release uses a separate build from release assets"
+          fi
+
   build:
     name: Build release artifacts
+    needs: validate-inputs
     runs-on: ubuntu-24.04
 
     steps:
@@ -101,27 +150,6 @@ jobs:
           name: mini-eq-dist
           path: dist
 
-      - name: Validate release inputs
-        env:
-          TAG_NAME: ${{ inputs.tag_name }}
-        run: |
-          set -euo pipefail
-
-          if [ -z "$TAG_NAME" ]; then
-            echo "::error::tag_name is required when create_github_release is true"
-            exit 1
-          fi
-
-          project_version="$(
-            python3 -c 'from pathlib import Path; import tomllib; print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])'
-          )"
-          expected_tag="v${project_version}"
-
-          if [ "$TAG_NAME" != "$expected_tag" ]; then
-            echo "::error::tag_name must be ${expected_tag} for pyproject version ${project_version}"
-            exit 1
-          fi
-
       - name: Create GitHub release
         env:
           DRAFT: ${{ inputs.draft }}
diff --git a/docs/release.md b/docs/release.md
@@ -202,9 +202,16 @@ as the release check when app/runtime routing behavior changed.
 ## Package Channels
 
 Use the `Release` workflow from GitHub Actions after local checks pass. Keep
-`dry_run=true` for packaging workflow changes. For real releases, keep the
-GitHub release as a draft first, review generated notes and assets, and publish
-the draft only after package-index checks pass.
+`dry_run=true` for packaging workflow changes. Every package-index or release
+dispatch must pass a `tag_name` that matches `pyproject.toml`.
+
+For real releases, keep the GitHub release as a draft first, review generated
+notes and assets, and publish the draft only after package-index checks pass.
+After TestPyPI validation, prefer one production workflow dispatch that creates
+the draft GitHub release and publishes to PyPI from the same built artifacts.
+That keeps the GitHub release files and PyPI files byte-for-byte comparable.
+Use a separate PyPI-only dispatch only as a recovery path, and document that it
+creates a second build.
 
 Use Trusted Publishing/OIDC for TestPyPI and PyPI. Do not use long-lived PyPI
 API tokens. Keep the `pypi` environment protected with required review before
@@ -252,10 +259,15 @@ python3 tools/release_post_publish.py "$version"
 
 `tools/release_post_publish.py` verifies that the GitHub release is no longer a
 draft, asset URLs use the stable tag instead of temporary `untagged-*` draft
-URLs, the remote tag exists, PyPI can see the version, and the downloaded source
-archive SHA-256 matches the GitHub release asset digest. Do not use draft
-release asset URLs for Flathub; use the printed source archive SHA-256 after
-the GitHub release is published.
+URLs, the remote tag exists, PyPI can see the exact version, the expected PyPI
+files exist, and downloaded GitHub release assets match their GitHub digest
+metadata. It also compares GitHub release asset hashes with PyPI artifact
+hashes and warns when they differ. Use `--strict-artifact-match` for releases
+that were intentionally published from a single workflow build and should have
+matching artifacts across channels.
+
+Do not use draft release asset URLs for Flathub; use the printed source archive
+SHA-256 after the GitHub release is published.
 
 ## Flathub Handoff
 
diff --git a/tests/test_release_post_publish.py b/tests/test_release_post_publish.py
@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+import subprocess
+
+import pytest
+
+from tools import release_post_publish
+
+
+def pypi_version_payload(version: str, *, sdist_sha: str, wheel_sha: str) -> bytes:
+    return json.dumps(
+        {
+            "info": {"version": version},
+            "urls": [
+                {
+                    "filename": release_post_publish.SDIST_NAME.format(version=version),
+                    "digests": {"sha256": sdist_sha},
+                },
+                {
+                    "filename": release_post_publish.WHEEL_NAME.format(version=version),
+                    "digests": {"sha256": wheel_sha},
+                },
+            ],
+        }
+    ).encode()
+
+
+def test_post_publish_checks_exact_pypi_version_and_warns_on_artifact_mismatch(monkeypatch, capsys) -> None:
+    version = "0.7.0"
+    sdist_name = release_post_publish.SDIST_NAME.format(version=version)
+    wheel_name = release_post_publish.WHEEL_NAME.format(version=version)
+
+    def fake_fetch_url(url: str, *, method: str = "GET") -> bytes:
+        assert method == "GET"
+        if url == release_post_publish.PYPI_VERSION_JSON_URL.format(version=version):
+            return pypi_version_payload(version, sdist_sha="pypi-sdist", wheel_sha="same-wheel")
+        if url == release_post_publish.PYPI_JSON_URL:
+            return json.dumps({"info": {"version": version}}).encode()
+        raise AssertionError(f"unexpected URL: {url}")
+
+    monkeypatch.setattr(release_post_publish, "fetch_url", fake_fetch_url)
+
+    release_post_publish.check_pypi(
+        version,
+        {sdist_name: "github-sdist", wheel_name: "same-wheel"},
+        strict_artifact_match=False,
+    )
+
+    captured = capsys.readouterr()
+    assert "PyPI version JSON reports: 0.7.0" in captured.out
+    assert "WARNING: PyPI and GitHub release artifact SHA-256 differ" in captured.err
+
+
+def test_post_publish_can_require_pypi_and_github_artifact_match(monkeypatch) -> None:
+    version = "0.7.0"
+    sdist_name = release_post_publish.SDIST_NAME.format(version=version)
+    wheel_name = release_post_publish.WHEEL_NAME.format(version=version)
+
+    def fake_fetch_url(url: str, *, method: str = "GET") -> bytes:
+        assert method == "GET"
+        if url == release_post_publish.PYPI_VERSION_JSON_URL.format(version=version):
+            return pypi_version_payload(version, sdist_sha="pypi-sdist", wheel_sha="same-wheel")
+        raise AssertionError(f"unexpected URL: {url}")
+
+    monkeypatch.setattr(release_post_publish, "fetch_url", fake_fetch_url)
+
+    with pytest.raises(SystemExit, match="PyPI and GitHub release artifact SHA-256 differ"):
+        release_post_publish.check_pypi(
+            version,
+            {sdist_name: "github-sdist", wheel_name: "same-wheel"},
+            strict_artifact_match=True,
+        )
+
+
+def test_post_publish_reads_stable_github_release_asset_hashes(monkeypatch) -> None:
+    version = "0.7.0"
+    tag = f"v{version}"
+    sdist_name = release_post_publish.SDIST_NAME.format(version=version)
+    wheel_name = release_post_publish.WHEEL_NAME.format(version=version)
+
+    monkeypatch.setattr(
+        release_post_publish,
+        "gh_json",
+        lambda _command: {
+            "tagName": tag,
+            "isDraft": False,
+            "isPrerelease": False,
+            "url": f"https://github.com/bhack/mini-eq/releases/tag/{tag}",
+            "assets": [
+                {
+                    "name": sdist_name,
+                    "url": f"https://github.com/bhack/mini-eq/releases/download/{tag}/{sdist_name}",
+                    "digest": "sha256:sdist-sha",
+                },
+                {
+                    "name": wheel_name,
+                    "url": f"https://github.com/bhack/mini-eq/releases/download/{tag}/{wheel_name}",
+                    "digest": "sha256:wheel-sha",
+                },
+            ],
+        },
+    )
+    monkeypatch.setattr(
+        release_post_publish,
+        "sha256_url",
+        lambda url: "sdist-sha" if url.endswith(".tar.gz") else "wheel-sha",
+    )
+    monkeypatch.setattr(
+        release_post_publish,
+        "run",
+        lambda command: subprocess.CompletedProcess(command, 0, stdout=f"abc123\trefs/tags/{tag}\n", stderr=""),
+    )
+
+    assert release_post_publish.check_github_release(version, tag, "bhack/mini-eq") == {
+        sdist_name: "sdist-sha",
+        wheel_name: "wheel-sha",
+    }
diff --git a/tools/release_post_publish.py b/tools/release_post_publish.py
@@ -6,6 +6,7 @@
 import json
 import shutil
 import subprocess
+import sys
 import tomllib
 import urllib.error
 import urllib.request
@@ -15,6 +16,7 @@
 ROOT = Path(__file__).resolve().parents[1]
 DEFAULT_REPO = "bhack/mini-eq"
 PYPI_JSON_URL = "https://pypi.org/pypi/mini-eq/json"
+PYPI_VERSION_JSON_URL = "https://pypi.org/pypi/mini-eq/{version}/json"
 PYPI_VERSION_URL = "https://pypi.org/project/mini-eq/{version}/"
 SDIST_NAME = "mini_eq-{version}.tar.gz"
 WHEEL_NAME = "mini_eq-{version}-py3-none-any.whl"
@@ -70,7 +72,7 @@ def asset_by_name(release: dict[str, Any], name: str) -> dict[str, Any]:
     raise SystemExit(f"GitHub release is missing asset: {name}")
 
 
-def check_github_release(version: str, tag: str, repo: str) -> str:
+def check_github_release(version: str, tag: str, repo: str) -> dict[str, str]:
     release = gh_json(
         [
             "gh",
@@ -90,33 +92,60 @@ def check_github_release(version: str, tag: str, repo: str) -> str:
         raise SystemExit(f"GitHub release {tag} is still a draft")
 
     expected_names = (SDIST_NAME.format(version=version), WHEEL_NAME.format(version=version))
+    asset_shas: dict[str, str] = {}
     for name in expected_names:
         asset = asset_by_name(release, name)
         url = asset["url"]
         if f"/download/{tag}/" not in url:
             raise SystemExit(f"GitHub release asset still has an unstable URL: {url}")
+        asset_sha = sha256_url(url)
+        asset_shas[name] = asset_sha
+        expected_digest = asset.get("digest")
+        if expected_digest and expected_digest != f"sha256:{asset_sha}":
+            raise SystemExit(
+                f"Downloaded GitHub release asset SHA-256 does not match the asset digest: "
+                f"{name}: {asset_sha} != {expected_digest}"
+            )
 
     tag_lookup = run(["git", "ls-remote", "--tags", "origin", tag])
     if not tag_lookup.stdout.strip():
         raise SystemExit(f"Remote tag not found on origin: {tag}")
 
-    sdist = asset_by_name(release, expected_names[0])
-    sdist_sha = sha256_url(sdist["url"])
-    expected_digest = sdist.get("digest")
-    if expected_digest and expected_digest != f"sha256:{sdist_sha}":
-        raise SystemExit(
-            f"Downloaded sdist SHA-256 does not match the GitHub release asset digest: {sdist_sha} != {expected_digest}"
-        )
-
     print(f"GitHub release is published: {release['url']}")
     print(f"Remote tag exists: {tag_lookup.stdout.strip()}")
-    print(f"Flathub source archive SHA-256: {sdist_sha}")
-    return sdist_sha
+    print(f"Flathub source archive SHA-256: {asset_shas[expected_names[0]]}")
+    return asset_shas
 
 
-def check_pypi(version: str) -> None:
-    pypi_json = json.loads(fetch_url(PYPI_JSON_URL))
-    json_version = pypi_json["info"]["version"]
+def check_pypi(version: str, github_shas: dict[str, str], *, strict_artifact_match: bool) -> None:
+    version_json = json.loads(fetch_url(PYPI_VERSION_JSON_URL.format(version=version)))
+    version_json_version = version_json["info"]["version"]
+    if version_json_version != version:
+        raise SystemExit(f"PyPI version JSON mismatch: expected {version}, got {version_json_version}")
+
+    pypi_files = {file["filename"]: file for file in version_json["urls"]}
+    expected_names = (SDIST_NAME.format(version=version), WHEEL_NAME.format(version=version))
+    for name in expected_names:
+        if name not in pypi_files:
+            raise SystemExit(f"PyPI is missing artifact: {name}")
+        pypi_sha = pypi_files[name]["digests"]["sha256"]
+        print(f"PyPI artifact: {name} sha256:{pypi_sha}")
+
+        github_sha = github_shas.get(name)
+        if github_sha and github_sha != pypi_sha:
+            message = (
+                f"PyPI and GitHub release artifact SHA-256 differ for {name}: "
+                f"pypi={pypi_sha} github={github_sha}. Publish both channels from the same release workflow run "
+                "when artifact parity is required."
+            )
+            if strict_artifact_match:
+                raise SystemExit(message)
+            print(f"WARNING: {message}", file=sys.stderr)
+
+    print(f"PyPI version JSON reports: {version_json_version}")
+
+    project_json = json.loads(fetch_url(PYPI_JSON_URL))
+    json_version = project_json["info"]["version"]
     version_url = PYPI_VERSION_URL.format(version=version)
 
     if json_version == version:
@@ -142,6 +171,11 @@ def parse_args() -> argparse.Namespace:
         help="release version to verify; defaults to pyproject.toml",
     )
     parser.add_argument("--repo", default=DEFAULT_REPO, help=f"GitHub repository; defaults to {DEFAULT_REPO}")
+    parser.add_argument(
+        "--strict-artifact-match",
+        action="store_true",
+        help="fail when GitHub release asset SHA-256 values differ from PyPI artifact SHA-256 values",
+    )
     return parser.parse_args()
 
 
@@ -151,8 +185,8 @@ def main() -> int:
     tag = f"v{version}"
 
     require_tools("gh", "git")
-    check_github_release(version, tag, args.repo)
-    check_pypi(version)
+    github_shas = check_github_release(version, tag, args.repo)
+    check_pypi(version, github_shas, strict_artifact_match=args.strict_artifact_match)
     print("Post-publish checks passed.")
     return 0
 
