feat: implement post-release status system

- Add update_release_notes() to append status to GitHub releases
- Implement find_pr_for_sha() for PR detection
- Prioritize release notes updates (critical) over PR comments (graceful)
- Add comprehensive test coverage following TDD principles
- Update create-release action to output release ID
- Integrate with GitHub Actions workflows

Author: drernie

.github/actions/create-release/action.yml

@@ -18,6 +18,9 @@ inputs:
     default: 'true'
 
 outputs:
+  release-id:
+    description: 'ID of the created release'
+    value: ${{ steps.create-release.outputs.id }}
   release-url:
     description: 'URL of the created release'
     value: ${{ steps.create-release.outputs.url }}
@@ -122,7 +125,7 @@ runs:
         path: dist/*.mcpb
         retention-days: 90
 
-    - name: Post release status to PR
+    - name: Post release status
       shell: bash
       env:
         GITHUB_TOKEN: ${{ github.token }}
@@ -132,5 +135,6 @@ runs:
           --release-url "${{ steps.create-release.outputs.url }}" \
           --pypi-url "${{ steps.package-urls.outputs.pypi-url }}" \
           --docker-image "${{ steps.docker-info.outputs.image-uri }}" \
+          --release-id "${{ steps.create-release.outputs.id }}" \
           --sha "${{ github.sha }}" \
           --repo "${{ github.repository }}"

scripts/post_release_status.py

@@ -1,9 +1,13 @@
 #!/usr/bin/env python3
 """
-Post release status comments to GitHub PRs.
+Post release status to GitHub releases and associated PRs.
 
-This script posts release information as a comment on associated PRs,
-including package locations, Docker images, and installation instructions.
+This script updates GitHub release notes with release information and optionally
+posts comments to associated PRs, including package locations, Docker images,
+and installation instructions.
+
+PRIMARY: Always update GitHub release notes (failure = workflow failure)
+SECONDARY: Post PR comment when possible (failure = graceful continue)
 """
 
 import argparse
@@ -53,7 +57,59 @@ def generate_release_comment(
     return body
 
 
-def find_pr_for_tag(github_token: str, repo: str, sha: str) -> Optional[int]:
+def update_release_notes(
+    github_token: str,
+    repo: str,
+    release_id: str,
+    additional_content: str,
+) -> bool:
+    """
+    Update GitHub release notes by appending status information.
+
+    Args:
+        github_token: GitHub API token
+        repo: Repository in "owner/repo" format
+        release_id: GitHub release ID
+        additional_content: Formatted status content to append
+
+    Returns:
+        True if successful, False otherwise
+    """
+    import requests
+
+    headers = {
+        "Authorization": f"token {github_token}",
+        "Accept": "application/vnd.github.v3+json",
+    }
+
+    # First, get the current release to preserve existing body
+    get_url = f"https://api.github.com/repos/{repo}/releases/{release_id}"
+
+    try:
+        response = requests.get(get_url, headers=headers)
+        response.raise_for_status()
+
+        release_data = response.json()
+        existing_body = release_data.get("body") or ""
+
+        # Append the additional content
+        updated_body = existing_body + additional_content
+
+        # Update the release with the new body
+        patch_url = f"https://api.github.com/repos/{repo}/releases/{release_id}"
+        patch_data = {"body": updated_body}
+
+        response = requests.patch(patch_url, headers=headers, json=patch_data)
+        response.raise_for_status()
+
+        return True
+
+    except requests.RequestException as e:
+        print(f"Error updating release notes: {e}", file=sys.stderr)
+        return False
+
+
+def find_pr_for_sha(github_token: str, repo: str, sha: str) -> Optional[int]:
     """
     Find the PR number associated with a git SHA.
 
@@ -89,6 +145,21 @@ def find_pr_for_tag(github_token: str, repo: str, sha: str) -> Optional[int]:
     return None
 
 
+def find_pr_for_tag(github_token: str, repo: str, sha: str) -> Optional[int]:
+    """
+    Legacy alias for find_pr_for_sha for backward compatibility.
+
+    Args:
+        github_token: GitHub API token
+        repo: Repository in format "owner/repo"
+        sha: Git commit SHA to search for
+
+    Returns:
+        PR number if found, None otherwise
+    """
+    return find_pr_for_sha(github_token, repo, sha)
+
+
 def post_comment_to_pr(
     github_token: str,
     repo: str,
@@ -129,7 +200,7 @@ def post_comment_to_pr(
 def main():
     """Main entry point."""
     parser = argparse.ArgumentParser(
-        description="Post release status to GitHub PRs"
+        description="Post release status to GitHub releases and PRs"
     )
     parser.add_argument(
         "--version",
@@ -150,6 +221,10 @@ def main():
         "--docker-image",
         help="Docker image URI",
     )
+    parser.add_argument(
+        "--release-id",
+        help="GitHub release ID for updating notes",
+    )
     parser.add_argument(
         "--pr-number",
         type=int,
@@ -177,8 +252,8 @@ def main():
 
     args = parser.parse_args()
 
-    # Generate the comment body
-    comment_body = generate_release_comment(
+    # Generate the status content
+    status_content = generate_release_comment(
         version=args.version,
         release_url=args.release_url,
         pypi_url=args.pypi_url,
@@ -187,48 +262,67 @@ def main():
 
     if args.dry_run:
         print("=== DRY RUN - Comment Body ===")
-        print(comment_body)
+        print(status_content)
         return 0
 
-    # Determine PR number
+    # PRIMARY GOAL: Update release notes if release-id is provided
+    if args.release_id:
+        if not args.github_token:
+            print("Error: GitHub token required to update release notes", file=sys.stderr)
+            return 1
+
+        if not args.repo:
+            print("Error: Repository required to update release notes", file=sys.stderr)
+            return 1
+
+        # Format content for release notes (add separator)
+        release_notes_content = f"\n---\n\n{status_content}"
+
+        success = update_release_notes(
+            github_token=args.github_token,
+            repo=args.repo,
+            release_id=args.release_id,
+            additional_content=release_notes_content,
+        )
+
+        if not success:
+            print("Failed to update release notes", file=sys.stderr)
+            return 1  # CRITICAL: Release notes update failure should fail the workflow
+
+        print(f"Updated release notes for release {args.release_id}")
+
+    # SECONDARY GOAL: Post PR comment if possible (failure = graceful continue)
     pr_number = args.pr_number
 
     if not pr_number and args.sha and args.github_token:
         # Try to find PR from SHA
-        pr_number = find_pr_for_tag(
+        pr_number = find_pr_for_sha(
             github_token=args.github_token,
             repo=args.repo,
             sha=args.sha,
         )
 
-    if not pr_number:
+    if pr_number and args.github_token and args.repo:
+        # Attempt to post PR comment
+        pr_success = post_comment_to_pr(
+            github_token=args.github_token,
+            repo=args.repo,
+            pr_number=pr_number,
+            comment_body=status_content,
+        )
+
+        if pr_success:
+            print(f"Posted release status to PR #{pr_number}")
+        else:
+            print(f"Warning: Failed to post comment to PR #{pr_number}", file=sys.stderr)
+            # Don't fail the workflow for PR comment failures
+    elif not args.release_id:
+        # Legacy behavior: if no release-id and no PR found, show status
         print("No PR found to comment on", file=sys.stderr)
         print("Release Status:")
-        print(comment_body)
-        return 0  # Not an error - just no PR to comment on
-
-    # Post the comment
-    if not args.github_token:
-        print("Error: GitHub token required to post comment", file=sys.stderr)
-        return 1
-
-    if not args.repo:
-        print("Error: Repository required to post comment", file=sys.stderr)
-        return 1
-
-    success = post_comment_to_pr(
-        github_token=args.github_token,
-        repo=args.repo,
-        pr_number=pr_number,
-        comment_body=comment_body,
-    )
+        print(status_content)
 
-    if success:
-        print(f"Posted release status to PR #{pr_number}")
-        return 0
-    else:
-        print(f"Failed to post comment to PR #{pr_number}", file=sys.stderr)
-        return 1
+    return 0
 
 
 if __name__ == "__main__":