fix(release): harden Discord announcement delivery

1jehuang · 1jehuang · commit 5d25773d9f86 · 2026-07-19T14:22:22.000-07:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -76,15 +76,25 @@ jobs:
         shell: bash
         run: python3 scripts/check_wildcard_reexport_budget.py
 
-      - name: Test Discord release announcements
-        run: python3 -m unittest -v scripts/test_post_discord_release.py
-
       - name: Enforce no unused dependencies
         shell: bash
         run: |
           cargo install cargo-machete --locked
           cargo machete
 
+  release-automation:
+    name: Release Automation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Test Discord release announcements
+        run: python3 -m unittest -v scripts/test_post_discord_release.py
+
+      - name: Compile release automation scripts
+        run: python3 -m py_compile scripts/post_discord_release.py scripts/test_post_discord_release.py
+
   build:
     name: Build & Test (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
diff --git a/.github/workflows/discord-release.yml b/.github/workflows/discord-release.yml
@@ -1,13 +1,22 @@
-name: Backfill Discord release announcement
+name: Announce release on Discord
 
 on:
+  # Covers releases published outside the tag-driven release workflow. Events
+  # created by GITHUB_TOKEN are suppressed, so release.yml also dispatches this
+  # workflow explicitly after it publishes a release.
+  release:
+    types: [published]
   workflow_dispatch:
     inputs:
       tag:
         description: Existing public release tag to announce
         required: true
         type: string
 
+concurrency:
+  group: discord-release-${{ inputs.tag || github.event.release.tag_name }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
 
@@ -16,9 +25,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
 
       - name: Post release notes to Discord if not already announced
         env:
           GH_TOKEN: ${{ github.token }}
           DISCORD_RELEASE_WEBHOOK: ${{ secrets.DISCORD_RELEASE_WEBHOOK }}
-        run: python3 scripts/post_discord_release.py --tag "${{ inputs.tag }}"
+          TAG: ${{ inputs.tag || github.event.release.tag_name }}
+        run: python3 scripts/post_discord_release.py --tag "$TAG"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -486,6 +486,9 @@ jobs:
     if: ${{ always() && needs.create-release.result == 'success' }}
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    permissions:
+      actions: write
+      contents: write
     steps:
       - uses: actions/checkout@v4
         with:
@@ -659,13 +662,16 @@ jobs:
             echo "Release ${GITHUB_REF_NAME} is already public; leaving it public."
           fi
 
-      # Do this in the publishing workflow itself. Releases created with
-      # GITHUB_TOKEN do not trigger a separate `release: published` workflow.
-      - name: Announce release on Discord
+      # Releases created with GITHUB_TOKEN do not trigger `release: published`,
+      # but workflow_dispatch is allowed. Queue the dedicated, per-tag
+      # announcement workflow without letting Discord block package publishing.
+      - name: Queue Discord release announcement
+        id: discord_announcement
+        continue-on-error: true
         env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
           GH_TOKEN: ${{ github.token }}
-          DISCORD_RELEASE_WEBHOOK: ${{ secrets.DISCORD_RELEASE_WEBHOOK }}
-        run: python3 scripts/post_discord_release.py --tag "${GITHUB_REF_NAME}"
+        run: gh workflow run discord-release.yml --ref "$DEFAULT_BRANCH" -f "tag=${GITHUB_REF_NAME}"
 
       - name: Update Homebrew formula
         env:
@@ -865,3 +871,9 @@ jobs:
               --reason completed
             gh issue edit "$issue" --remove-label "$label" || true
           done
+
+      - name: Report Discord announcement queue failure
+        if: always() && steps.discord_announcement.outcome == 'failure'
+        run: |
+          echo "The release was published, but its Discord announcement could not be queued." >&2
+          exit 1
diff --git a/scripts/post_discord_release.py b/scripts/post_discord_release.py
@@ -2,10 +2,9 @@
 """Post one GitHub release announcement to a Discord webhook.
 
 The release workflow publishes releases with GitHub's built-in GITHUB_TOKEN.
-GitHub deliberately does not emit a second workflow run for most events created
-by that token, so a separate ``release: published`` workflow is not reliable.
-This script is called directly by the release workflow and by a manual backfill
-workflow.
+GitHub deliberately suppresses most follow-up events created by that token, so
+the publisher explicitly dispatches the same workflow used for external release
+events and manual backfills.
 """
 
 from __future__ import annotations
@@ -129,6 +128,8 @@ def mark_release_announced(
 ) -> None:
     body = release.get("body") or ""
     marker = announcement_marker(tag)
+    if marker in body:
+        return
     updated_body = f"{body.rstrip()}\n\n{marker}\n"
     github_request(
         f"https://api.github.com/repos/{repository}/releases/{release['id']}",
@@ -151,6 +152,45 @@ def required(value: str | None, description: str) -> str:
     raise SystemExit(f"Missing {description}")
 
 
+def announce_release(
+    *, repository: str, tag: str, token: str, webhook_url: str
+) -> str | None:
+    release = fetch_release(repository=repository, tag=tag, token=token)
+    if release.get("draft"):
+        raise RuntimeError(f"Refusing to announce draft release {tag}")
+
+    body = release.get("body") or ""
+    if already_announced(body, tag):
+        print(f"Discord announcement for {tag} is already recorded; skipping")
+        return None
+
+    content = format_message(
+        tag=tag,
+        name=release.get("name") or tag,
+        body=body,
+        url=release["html_url"],
+    )
+    message = post_to_discord(webhook_url=webhook_url, content=content)
+    message_id = str(message["id"])
+    print(f"Posted {tag} to Discord as message {message_id}")
+
+    # Re-fetch immediately before patching so an edit made while the Discord
+    # request was in flight is not overwritten with the initially fetched body.
+    latest_release = fetch_release(repository=repository, tag=tag, token=token)
+    try:
+        mark_release_announced(
+            repository=repository, release=latest_release, tag=tag, token=token
+        )
+    except Exception as error:  # noqa: BLE001 - best-effort after public side effect
+        # A marker write failure must not turn a successful public post into a
+        # failed workflow that an operator is likely to rerun and duplicate.
+        print(
+            f"::warning::Discord post succeeded, but the release marker failed: {error}",
+            file=sys.stderr,
+        )
+    return message_id
+
+
 def main() -> int:
     args = parse_args()
     tag = required(args.tag, "release tag (--tag or GITHUB_REF_NAME)")
@@ -165,38 +205,20 @@ def main() -> int:
     )
 
     try:
-        release = fetch_release(repository=repository, tag=tag, token=token)
-        body = release.get("body") or ""
-        if already_announced(body, tag):
-            print(f"Discord announcement for {tag} is already recorded; skipping")
-            return 0
-
-        content = format_message(
+        announce_release(
+            repository=repository,
             tag=tag,
-            name=release.get("name") or tag,
-            body=body,
-            url=release["html_url"],
+            token=token,
+            webhook_url=webhook_url,
         )
-        message = post_to_discord(webhook_url=webhook_url, content=content)
-        print(f"Posted {tag} to Discord as message {message['id']}")
-
-        # The marker makes workflow reruns and manual backfills idempotent. A
-        # marker write failure must not turn a successful public post into a
-        # failed workflow that an operator is likely to rerun and duplicate.
-        try:
-            mark_release_announced(
-                repository=repository, release=release, tag=tag, token=token
-            )
-        except Exception as error:  # noqa: BLE001 - best-effort after public side effect
-            print(
-                f"::warning::Discord post succeeded, but the release marker failed: {error}",
-                file=sys.stderr,
-            )
         return 0
     except urllib.error.HTTPError as error:
         detail = error.read().decode("utf-8", errors="replace")
         print(f"HTTP {error.code} while announcing {tag}: {detail}", file=sys.stderr)
         return 1
+    except (RuntimeError, urllib.error.URLError) as error:
+        print(f"Could not announce {tag}: {error}", file=sys.stderr)
+        return 1
 
 
 if __name__ == "__main__":
diff --git a/scripts/test_post_discord_release.py b/scripts/test_post_discord_release.py
@@ -9,6 +9,7 @@
 import threading
 import unittest
 import urllib.error
+from unittest import mock
 
 
 SCRIPT = Path(__file__).with_name("post_discord_release.py")
@@ -118,6 +119,78 @@ def test_rejected_webhook_raises_http_error(self) -> None:
             thread.join()
             server.server_close()
 
+    def test_announce_skips_an_existing_marker(self) -> None:
+        release = {
+            "id": 52,
+            "name": "v0.52.0",
+            "body": "notes\n<!-- jcode-discord-announced:v0.52.0 -->",
+            "html_url": "https://example.test/v0.52.0",
+            "draft": False,
+        }
+        with (
+            mock.patch.object(MODULE, "fetch_release", return_value=release),
+            mock.patch.object(MODULE, "post_to_discord") as post,
+        ):
+            result = MODULE.announce_release(
+                repository="owner/repo",
+                tag="v0.52.0",
+                token="token",
+                webhook_url="https://discord.test/webhook",
+            )
+        self.assertIsNone(result)
+        post.assert_not_called()
+
+    def test_announce_rejects_draft_release(self) -> None:
+        release = {
+            "id": 53,
+            "name": "v0.53.0",
+            "body": "notes",
+            "html_url": "https://example.test/v0.53.0",
+            "draft": True,
+        }
+        with (
+            mock.patch.object(MODULE, "fetch_release", return_value=release),
+            mock.patch.object(MODULE, "post_to_discord") as post,
+            self.assertRaisesRegex(RuntimeError, "draft release"),
+        ):
+            MODULE.announce_release(
+                repository="owner/repo",
+                tag="v0.53.0",
+                token="token",
+                webhook_url="https://discord.test/webhook",
+            )
+        post.assert_not_called()
+
+    def test_announce_refetches_before_writing_marker(self) -> None:
+        initial = {
+            "id": 54,
+            "name": "v0.54.0",
+            "body": "initial notes",
+            "html_url": "https://example.test/v0.54.0",
+            "draft": False,
+        }
+        latest = {**initial, "body": "notes edited during post"}
+        with (
+            mock.patch.object(MODULE, "fetch_release", side_effect=[initial, latest]),
+            mock.patch.object(
+                MODULE, "post_to_discord", return_value={"id": "message-54"}
+            ),
+            mock.patch.object(MODULE, "mark_release_announced") as mark,
+        ):
+            result = MODULE.announce_release(
+                repository="owner/repo",
+                tag="v0.54.0",
+                token="token",
+                webhook_url="https://discord.test/webhook",
+            )
+        self.assertEqual(result, "message-54")
+        mark.assert_called_once_with(
+            repository="owner/repo",
+            release=latest,
+            tag="v0.54.0",
+            token="token",
+        )
+
 
 if __name__ == "__main__":
     unittest.main()
