release: automate GitHub Releases

Author: monarchjuno

.github/workflows/release.yml

@@ -197,3 +197,61 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-github-release:
+    name: Publish v${{ inputs.release_version }} GitHub Release
+    needs: publish-pypi
+    if: inputs.publish_pypi == 'true' && github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Check out release notes
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Download exact distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: tradingcodex-${{ inputs.release_version }}
+          path: dist/
+
+      - name: Extract matching changelog section
+        env:
+          RELEASE_VERSION: ${{ inputs.release_version }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          from pathlib import Path
+
+          version = re.escape(os.environ["RELEASE_VERSION"])
+          changelog = Path("CHANGELOG.md").read_text(encoding="utf-8")
+          match = re.search(
+              rf"^## {version} - .*$\n.*?(?=^## |\Z)",
+              changelog,
+              flags=re.MULTILINE | re.DOTALL,
+          )
+          if match is None:
+              raise SystemExit(f"missing CHANGELOG.md section for {os.environ['RELEASE_VERSION']}")
+          Path("release-notes.md").write_text(match.group(0).strip() + "\n", encoding="utf-8")
+          PY
+
+      - name: Create or update GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ inputs.release_version }}
+        run: |
+          tag="v${RELEASE_VERSION}"
+          title="TradingCodex ${RELEASE_VERSION}"
+          assets=(
+            "dist/tradingcodex-${RELEASE_VERSION}-py3-none-any.whl"
+            "dist/tradingcodex-${RELEASE_VERSION}.tar.gz"
+          )
+          if gh release view "$tag" >/dev/null 2>&1; then
+            gh release edit "$tag" --title "$title" --notes-file release-notes.md
+            gh release upload "$tag" "${assets[@]}" --clobber
+          else
+            gh release create "$tag" "${assets[@]}" --verify-tag --title "$title" --notes-file release-notes.md
+          fi

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- Create or refresh the GitHub Release from the exact verified distributions
+  and matching changelog section only after protected PyPI publication succeeds.
+
 ## 1.2.0 - 2026-07-20
 
 - Refresh the manual GitHub Pages workflow to the current Node 24 action

docs/deployment.md

@@ -204,10 +204,12 @@ requests and pushes still receive the normal source-quality checks.
 The release workflow has one build/verification job followed by the required
 Python 3.11-3.14 Linux, Intel-macOS, and native-Windows calculation-runtime
 matrix. When publication is requested, one protected PyPI job downloads that
-exact artifact and uploads it; no job rebuilds the distribution after
-verification. These distribution and platform jobs run only after an explicit
-`Manual Release` dispatch, never because a branch, tag, development commit, or
-documentation change was pushed.
+exact artifact and uploads it. After PyPI succeeds, a GitHub Release job
+downloads the same artifact, uses the matching `CHANGELOG.md` section as its
+notes, and creates or refreshes the tag's wheel and source-distribution assets.
+No job rebuilds the distribution after verification. These distribution and
+platform jobs run only after an explicit `Manual Release` dispatch, never
+because a branch, tag, development commit, or documentation change was pushed.
 
 ## User Guide Pages
 
@@ -246,7 +248,8 @@ The guide for this repository is published at
 5. In GitHub Actions, run `Manual Release` from that tag with the exact
    `release_version`. Use `publish_pypi=true` for an approved publication; use
    the optional `publish_pypi=false` rehearsal when release risk warrants an
-   additional hosted build.
+   additional hosted build. A successful approved publication also creates or
+   refreshes the matching GitHub Release from the verified artifacts.
 
 Pushing a branch or tag does not publish by itself.
 

tests/test_release_contract.py

@@ -656,7 +656,7 @@ def test_release_publish_is_tag_bound_and_reuses_one_verified_build() -> None:
     assert "parse_wheel_filename" in distribution["run"]
     assert "actual_artifacts != expected_artifacts" in distribution["run"]
     assert "unexpected distribution files" in distribution["run"]
-    assert set(jobs) == {"build", "calculation-runtime-matrix", "publish-pypi"}
+    assert set(jobs) == {"build", "calculation-runtime-matrix", "publish-pypi", "publish-github-release"}
     runtime_matrix = jobs["calculation-runtime-matrix"]
     assert runtime_matrix["needs"] == "build"
     assert runtime_matrix["strategy"]["fail-fast"] is False
@@ -685,6 +685,22 @@ def test_release_publish_is_tag_bound_and_reuses_one_verified_build() -> None:
     assert any("download-artifact" in step.get("uses", "") for step in jobs["publish-pypi"]["steps"])
     assert not any("python -m build" in step.get("run", "") for step in jobs["publish-pypi"]["steps"])
 
+    github_release = jobs["publish-github-release"]
+    assert github_release["needs"] == "publish-pypi"
+    assert github_release["if"] == "inputs.publish_pypi == 'true' && github.ref_type == 'tag'"
+    assert github_release["permissions"] == {"contents": "write"}
+    release_job_steps = "\n".join(str(step.get("run", "")) for step in github_release["steps"])
+    assert any("actions/checkout@v6" in step.get("uses", "") for step in github_release["steps"])
+    assert any("download-artifact" in step.get("uses", "") for step in github_release["steps"])
+    assert "CHANGELOG.md" in release_job_steps
+    assert "release-notes.md" in release_job_steps
+    assert "gh release create" in release_job_steps
+    assert "gh release edit" in release_job_steps
+    assert "gh release upload" in release_job_steps
+    assert '"${assets[@]}" --clobber' in release_job_steps
+    assert "python -m build" not in release_job_steps
+    assert "gh-action-pypi-publish" not in release_job_steps
+
 
 def test_normal_github_uploads_do_not_build_or_deploy_release_artifacts() -> None:
     ci = yaml.safe_load((ROOT / ".github/workflows/ci.yml").read_text(encoding="utf-8"))