From 3cf6ac3211f0137d506eee55c03aa018aa29bd38 Mon Sep 17 00:00:00 2001
From: arnavchachra <mail@arnav.ch>
Date: Tue, 14 Jul 2026 18:49:44 +0530
Subject: [PATCH 1/4] feat(notify): support alert cards via header/color/status
 overrides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The notify card was locked to a deploy result: a green/red header derived
from `result`, a Version field, and a pass/fail color bar. Callers that need
the same card shape for a non-deploy alert (e.g. a merge-revert / guard notice)
had to hand-roll the whole jq payload and curl themselves.

Add three optional, backward-compatible inputs:

- `header` — full header line, verbatim, overriding the default
  "<emoji> <label> — <status>". May carry Slack emoji shortcodes.
- `color`  — hex color bar overriding the result-derived green/red.
- `status` — when set, the first field renders as "Status" with this text
  in place of the "Version" field.

PR/commit resolution, the body section, and the context line are untouched,
so an alert card still shows the PR (or commit) that `target-sha` traces to.
With none of the three set the payload is byte-identical to before, so existing
deploy callers are unaffected. Documented in the README notify table.
---
 README.md                 | 10 ++++++++
 actions/notify/action.yml | 49 ++++++++++++++++++++++++++++++++++-----
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index d130119..3f3845c 100644
--- a/README.md
+++ b/README.md
@@ -287,12 +287,22 @@ local-timezone message timestamp.
 Best-effort: an empty `webhook-url` is a no-op that still succeeds, and a failed
 post never fails the pipeline.
 
+The `header`, `color`, and `status` inputs turn the same card into a general
+**alert** (e.g. a revert or guard notice) instead of a deploy result: supply a
+custom title and color bar, and the first field becomes **Status** instead of
+**Version**. The PR/commit resolution, body, and context line are unchanged, so
+the card still shows the PR (or commit) that `target-sha` traces to. Omit all
+three and the card is exactly the deploy-result card above.
+
 | Input | Required | Default | Description |
 |-------|----------|---------|-------------|
 | `result` | yes | — | `success` / `failure` — e.g. a deploy job's `result`. Anything other than `success` renders as failed. |
 | `webhook-url` | no | `''` | Slack incoming webhook URL. Empty makes the action a no-op. |
 | `label` | no | `Deployment` | Short label for the card header (app / component name). |
 | `version` | no | `''` | Version string shown in the Version field (`n/a` if empty). |
+| `header` | no | `''` | Full header line, verbatim, overriding the default `<emoji> <label> — <status>`. May contain Slack emoji shortcodes. |
+| `color` | no | `''` | Attachment bar color (hex) overriding the result-derived green/red. |
+| `status` | no | `''` | When set, the first field renders as **Status** with this text in place of the **Version** field. |
 | `channel` | no | `slack` | Chat channel; only `slack` is implemented today. |
 | `github-token` | no | `${{ github.token }}` | Token used to read the PR/commit. The default job token covers a same-repo deploy; for a cross-org deploy pass a token minted in the caller from a GitHub App with read access to `target-repo`. |
 | `target-repo` | no | `${{ github.repository }}` | `owner/repo` whose PR/commit the card describes. Override for a cross-repo deploy. |
diff --git a/actions/notify/action.yml b/actions/notify/action.yml
index b6f7c36..9439774 100644
--- a/actions/notify/action.yml
+++ b/actions/notify/action.yml
@@ -23,6 +23,26 @@ inputs:
     description: Version string shown in the message.
     required: false
     default: ""
+  header:
+    description: >-
+      Full header line, verbatim. When set, overrides the default
+      "<emoji> <label> — <succeeded|failed>" header — for alert cards that need
+      a custom title (e.g. a revert notice). May contain Slack emoji shortcodes.
+    required: false
+    default: ""
+  color:
+    description: >-
+      Attachment bar color (hex, e.g. "#F9A825"). When set, overrides the
+      result-derived green/red — lets alert callers signal a state that isn't a
+      clean pass/fail.
+    required: false
+    default: ""
+  status:
+    description: >-
+      When set, the first card field renders as "*Status*\n<status>" in place of
+      "*Version*\n<version>". For alert cards where a version is meaningless.
+    required: false
+    default: ""
   channel:
     description: "Chat channel: slack (only slack implemented today)."
     required: false
@@ -58,6 +78,9 @@ runs:
         RESULT: ${{ inputs.result }}
         LABEL: ${{ inputs.label }}
         VERSION: ${{ inputs.version }}
+        HEADER_IN: ${{ inputs.header }}
+        COLOR_IN: ${{ inputs.color }}
+        STATUS_IN: ${{ inputs.status }}
         WEBHOOK: ${{ inputs.webhook-url }}
         TARGET_REPO: ${{ inputs.target-repo }}
         TARGET_SHA: ${{ inputs.target-sha }}
@@ -78,6 +101,18 @@ runs:
         version="${VERSION:-}"; [ -z "$version" ] && version="n/a"
         short_sha="${TARGET_SHA:0:7}"
 
+        # Card chrome. Alert callers can override the header line and color bar,
+        # and swap the first field from Version to Status. With none of these
+        # inputs set, the result-derived defaults reproduce the original card
+        # verbatim, so existing deploy callers are unaffected.
+        header="${HEADER_IN:-${emoji} ${LABEL} — ${status}}"
+        [ -n "${COLOR_IN:-}" ] && color="$COLOR_IN"
+        if [ -n "${STATUS_IN:-}" ]; then
+          field1_label="Status"; field1_value="$STATUS_IN"
+        else
+          field1_label="Version"; field1_value="$version"
+        fi
+
         # Build date in UTC (YYYY.MM.DD), shown on the card so the deploy date is
         # unambiguous rather than inferred from Slack's local-timezone timestamp.
         built_utc="$(date -u +%Y.%m.%d)"
@@ -95,15 +130,16 @@ runs:
           pr_url="$(jq -r '.html_url // ""' <<<"$sel")"
           pr_user="$(jq -r '.user.login // "unknown"' <<<"$sel")"
           payload="$(jq -n \
-            --arg color "$color" --arg header "${emoji} ${LABEL} — ${status}" \
-            --arg version "$version" --arg prlabel "${TARGET_REPO}#${pr_num}" --arg title "$pr_title" \
+            --arg color "$color" --arg header "$header" \
+            --arg f1label "$field1_label" --arg f1value "$field1_value" \
+            --arg prlabel "${TARGET_REPO}#${pr_num}" --arg title "$pr_title" \
             --arg user "$pr_user" --arg runurl "$RUN_URL" --arg prurl "$pr_url" \
             --arg built "$built_utc" '
             def esc: gsub("&";"&amp;") | gsub("<";"&lt;") | gsub(">";"&gt;");
             { attachments: [{ color: $color, blocks: [
                 { type:"header", text:{ type:"plain_text", text:$header, emoji:true } },
                 { type:"section", fields:[
-                    { type:"mrkdwn", text:("*Version*\n" + $version) },
+                    { type:"mrkdwn", text:("*" + $f1label + "*\n" + $f1value) },
                     { type:"mrkdwn", text:("*PR*\n" + (if $prurl != "" then "<" + $prurl + "|" + $prlabel + ">" else $prlabel end)) } ]},
                 { type:"section", text:{ type:"mrkdwn", text:("*" + ($title|esc) + "*") } },
                 { type:"context", elements:[
@@ -119,15 +155,16 @@ runs:
           if [ -n "$c_subject" ]; then
             # Commit card: subject + short SHA (linked) + author.
             payload="$(jq -n \
-              --arg color "$color" --arg header "${emoji} ${LABEL} — ${status}" \
-              --arg version "$version" --arg short "$short_sha" --arg cmurl "$c_url" \
+              --arg color "$color" --arg header "$header" \
+              --arg f1label "$field1_label" --arg f1value "$field1_value" \
+              --arg short "$short_sha" --arg cmurl "$c_url" \
               --arg subject "$c_subject" --arg user "$c_author" --arg runurl "$RUN_URL" \
               --arg built "$built_utc" '
               def esc: gsub("&";"&amp;") | gsub("<";"&lt;") | gsub(">";"&gt;");
               { attachments: [{ color: $color, blocks: [
                   { type:"header", text:{ type:"plain_text", text:$header, emoji:true } },
                   { type:"section", fields:[
-                      { type:"mrkdwn", text:("*Version*\n" + $version) },
+                      { type:"mrkdwn", text:("*" + $f1label + "*\n" + $f1value) },
                       { type:"mrkdwn", text:("*Commit*\n" + (if $cmurl != "" then "<" + $cmurl + "|" + $short + ">" else "`" + $short + "`" end)) } ]},
                   { type:"section", text:{ type:"mrkdwn", text:("*" + ($subject|esc) + "*") } },
                   { type:"context", elements:[

From 0dae2e9d5be5f367738b556b288d472135f9c65c Mon Sep 17 00:00:00 2001
From: arnavchachra <mail@arnav.ch>
Date: Wed, 15 Jul 2026 17:48:13 +0530
Subject: [PATCH 2/4] feat(empty-pr-guard): add reusable merge-time
 empty-PR-description gate

Extract the empty-description merge guard (previously an inline ~100-line job
in a consumer's deploy pipeline) into a reusable workflow so every repo can
adopt it with one `uses:` instead of copy-pasting the bash.

On a push, it resolves the PR behind HEAD and, if the body is empty/whitespace,
reverts the merge (via `-m 1` for merge commits or the `before..HEAD` range for
squash/rebase), edits the PR to explain, posts a Slack card via the shared
notify action, and emits `block=true` so the caller stands its release down.
Fails safe on a PR-fetch API error; keeps block=true and asks for a manual
revert on a rejected push or conflict.

Because the Slack webhook is an environment secret and a reusable-workflow
caller job can't declare an environment, the workflow declares it from the
`environment` input and the caller passes `secrets: inherit`. `label` sets the
alert header name.

The notify call is pinned to feat/empty-pr-guard for now (same branch); bump to
@v3 on release. Documented in the README.
---
 .github/workflows/empty-pr-guard.yml | 183 +++++++++++++++++++++++++++
 README.md                            |  43 +++++++
 2 files changed, 226 insertions(+)
 create mode 100644 .github/workflows/empty-pr-guard.yml

diff --git a/.github/workflows/empty-pr-guard.yml b/.github/workflows/empty-pr-guard.yml
new file mode 100644
index 0000000..7053ed3
--- /dev/null
+++ b/.github/workflows/empty-pr-guard.yml
@@ -0,0 +1,183 @@
+name: Empty PR-description guard
+
+# Reusable merge-time gate. On a push to a protected branch, find the PR behind
+# HEAD and, if it merged with an empty (or whitespace-only) description, revert
+# the merge, edit the PR to explain, alert Slack, and emit block=true so the
+# caller can stand its release/build/deploy jobs down (we don't ship code we're
+# reverting). This is the merge-time backstop for enforcing PR descriptions.
+#
+# The caller decides *when* this runs (its own `if:`, e.g. only on dev pushes)
+# and grants the token scopes; this workflow operates on whatever branch the
+# push targeted (github.ref_name) and resolves the PR from github.sha.
+#
+# What gets reverted depends on how the PR landed:
+#   • merge commit (>=2 parents) → `git revert -m 1` undoes the whole PR.
+#   • squash (1 commit) / rebase (N commits) → revert every commit this push
+#     introduced (`before..HEAD`), so a multi-commit rebase is fully undone.
+#
+# Fail behaviour:
+#   • PR-fetch API error → fail SAFE: skip (block=false), never false-revert.
+#   • revert push rejected / conflicts → block stays true, Slack says "revert by
+#     hand", and the caller (which gates on this workflow's result) stands down.
+#
+# Secrets: the Slack webhook is typically an *environment* secret, and a job
+# that calls a reusable workflow can't declare an environment. So this workflow
+# declares the environment (from `environment` input) and the caller passes
+# `secrets: inherit`; SLACK_WEBHOOK_URL then resolves from the caller's env.
+
+on:
+  workflow_call:
+    inputs:
+      environment:
+        description: >-
+          Caller environment to run under; its secrets must expose
+          SLACK_WEBHOOK_URL. Required because the webhook is an environment
+          secret and a reusable-workflow caller job cannot declare an
+          environment itself.
+        required: true
+        type: string
+      label:
+        description: Short name shown in the Slack alert header (e.g. "Backend", "Web").
+        required: false
+        type: string
+        default: Service
+    outputs:
+      block:
+        description: "'true' when the merge was reverted and the caller's release must stand down."
+        value: ${{ jobs.guard.outputs.block }}
+
+permissions: {}
+
+jobs:
+  guard:
+    name: Gate
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    permissions:
+      contents: write        # push the revert commit
+      pull-requests: write   # edit the reverted PR description
+    outputs:
+      block: ${{ steps.check.outputs.block }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          ref: ${{ github.ref_name }}
+          fetch-depth: 0   # full history so the merge commit is revertable
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Revert empty-description merge
+        id: check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.sha }}
+          BEFORE: ${{ github.event.before }}
+          BASE_REF: ${{ github.ref_name }}
+          LABEL: ${{ inputs.label }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          block=false
+
+          # Find the PR that introduced this commit. Empty for a direct push
+          # (no PR) — that's branch-protection's job, not ours.
+          pr_json="$(gh api "repos/$REPO/commits/$SHA/pulls" \
+              -H "Accept: application/vnd.github+json" 2>/dev/null || echo '[]')"
+          pr_number="$(jq -r 'map(select(.merged_at != null)) | (.[0].number // empty)' <<<"$pr_json")"
+
+          if [ -z "$pr_number" ]; then
+            echo "No merged PR associated with $SHA (direct push?); nothing to enforce."
+          else
+            # Fetch the PR body in one call. Fail SAFE: if the API call fails
+            # (rate limit, network), do NOT treat it as an empty description —
+            # that would revert a legitimate merge. Skip the guard and proceed.
+            pr="$(gh pr view "$pr_number" --repo "$REPO" --json body 2>/dev/null)" || {
+              echo "::warning::Could not fetch PR #$pr_number; skipping description guard for $SHA."
+              echo "block=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            }
+            pr_body="$(jq -r '.body // ""' <<<"$pr")"
+
+            if [ -n "$(printf '%s' "$pr_body" | tr -d '[:space:]')" ]; then
+              echo "PR #$pr_number has a description; proceeding."
+            else
+              echo "PR #$pr_number merged with an empty description — reverting $SHA."
+              block=true
+              # Persist block early so a later failure in this branch can't fail
+              # open and let the reverted code ship (last write to the file wins).
+              echo "block=true" >> "$GITHUB_OUTPUT"
+
+              # merge commit (>=3 tokens: self + 2 parents) → revert via -m 1;
+              # squash/rebase → revert the whole before..HEAD range.
+              parents="$(git rev-list --parents -n 1 "$SHA" | wc -w)"
+              if [ "$parents" -ge 3 ]; then
+                revert_target="$SHA"; margs="-m 1"
+              else
+                revert_target="${BEFORE}..${SHA}"; margs=""
+              fi
+
+              outcome=""
+              # shellcheck disable=SC2086
+              if git revert --no-edit $margs $revert_target; then
+                if git push origin "HEAD:$BASE_REF"; then
+                  outcome="reverted"
+                  rsha="$(git rev-parse HEAD)"
+                  # Write the revert notice into the PR description itself (not a
+                  # comment) so it's visible at the top of the PR. The body was
+                  # empty (that's what tripped the guard), so setting it is safe —
+                  # nothing to preserve. Editing a merged PR's body is allowed.
+                  gh pr edit "$pr_number" --repo "$REPO" \
+                    --body "> ⚠️ **Auto-reverted on \`$BASE_REF\` (${rsha:0:7})** — this PR merged with an empty description, so the release was stood down and the merge reverted. Add a summary of *what* changed and *why*, then open a new PR." || true
+                  echo "::warning::Reverted $SHA on $BASE_REF as ${rsha:0:7}; skipping this release."
+                else
+                  outcome="push_failed"
+                  echo "::error::Revert commit created but push to $BASE_REF was rejected (branch protection?); manual revert needed."
+                fi
+              else
+                git revert --abort || true
+                outcome="conflict"
+                echo "::error::Auto-revert of $SHA conflicts with later commits; manual revert needed."
+              fi
+
+              # Per-outcome alert content. The Slack card itself is rendered by
+              # the notify step below (the shared notify action), which resolves
+              # the PR from github.sha for the title/link/author. We only supply
+              # the header, color bar, and Status text here.
+              case "$outcome" in
+                reverted)    color="#F9A825"; header=":leftwards_arrow_with_hook: ${LABEL} — merge reverted (empty description)"; reason="Merge reverted on \`${BASE_REF}\` (${rsha:0:7}); release skipped" ;;
+                push_failed) color="#D32F2F"; header=":rotating_light: ${LABEL} — revert blocked (empty description)"; reason="Revert push to \`${BASE_REF}\` rejected (branch protection); revert by hand" ;;
+                conflict)    color="#D32F2F"; header=":rotating_light: ${LABEL} — MANUAL revert needed (empty description)"; reason="Auto-revert conflicted on \`${BASE_REF}\`; revert by hand" ;;
+                *)           color="#D32F2F"; header=":rotating_light: ${LABEL} — empty-description merge"; reason="Revert outcome unknown; check the run" ;;
+              esac
+
+              {
+                echo "outcome=$outcome"
+                echo "color=$color"
+                echo "header=$header"
+                echo "reason=$reason"
+              } >> "$GITHUB_OUTPUT"
+            fi
+          fi
+
+          echo "block=$block" >> "$GITHUB_OUTPUT"
+
+      # Render the revert alert as a Slack card via the shared notify action —
+      # same card shape as the deploy announce, so both read consistently. Fires
+      # only when the guard acted (outcome set). target-sha/target-repo default
+      # to the caller's github.sha/github.repository, so notify resolves the
+      # empty-description PR for the card's title/link/author.
+      #
+      # Pinned to feat/empty-pr-guard for now (same branch as this workflow);
+      # bump to @v3 when this releases.
+      - name: Announce revert on Slack
+        if: steps.check.outputs.outcome != ''
+        uses: nurdsoft/ci-workflows/actions/notify@feat/empty-pr-guard
+        with:
+          result: failure
+          webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
+          label: ${{ inputs.label }}
+          header: ${{ steps.check.outputs.header }}
+          color: ${{ steps.check.outputs.color }}
+          status: ${{ steps.check.outputs.reason }}
diff --git a/README.md b/README.md
index 3f3845c..ce0282e 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,7 @@ behind a runner contract you control (or pass inline via `run`).
 | Path | Type | Function |
 |------|------|----------|
 | `.github/workflows/version.yml` | Reusable workflow | Cut a SemVer release — detects RC line, cuts the release, and creates the next RC baseline automatically |
+| `.github/workflows/empty-pr-guard.yml` | Reusable workflow | Merge-time gate — revert a merge whose PR had an empty description, alert Slack, and emit `block` so the caller stands its release down |
 | `actions/auth`   | Action | Obtain cloud credentials (OIDC) |
 | `actions/setup`  | Action | Install runtime + deps (+ EAS login) |
 | `actions/verify` | Action | Lint / type-check / test |
@@ -274,6 +275,48 @@ version:
     changelog-on-rc: true
 ```
 
+## empty-pr-guard.yml — inputs
+
+Merge-time gate that enforces non-empty PR descriptions. Call it as the **first
+job** of your pipeline, gated to the branch you protect. On a push whose merge
+commit traces to a PR with an empty (or whitespace-only) body, it reverts the
+merge on that branch, edits the PR to explain, posts a Slack card (via
+`notify`), and sets `block=true`; wire your downstream jobs to stand down when
+`needs.<guard>.outputs.block == 'true'`. A PR-fetch API error fails **safe**
+(skips, never false-reverts); a rejected push or a revert conflict keeps
+`block=true` and the Slack card asks for a manual revert.
+
+It reverts a merge commit via `git revert -m 1` and a squash/rebase merge via
+the `before..HEAD` range, so all three GitHub merge styles are fully undone.
+
+| Input | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `environment` | string | yes | — | Caller environment to run under; its secrets must expose `SLACK_WEBHOOK_URL`. Required because the webhook is an environment secret and a reusable-workflow caller job cannot declare an environment itself. |
+| `label` | string | no | `Service` | Short name shown in the Slack alert header (e.g. `Backend`, `Web`). |
+
+Output `block` (`'true'`/`'false'`) — gate downstream jobs on it. Pass
+`secrets: inherit` so `SLACK_WEBHOOK_URL` resolves from the caller's
+environment, and grant `contents: write` + `pull-requests: write`.
+
+```yaml
+jobs:
+  guard:
+    if: github.event_name == 'push' && github.ref_name == 'dev'
+    permissions: { contents: write, pull-requests: write }
+    uses: nurdsoft/ci-workflows/.github/workflows/empty-pr-guard.yml@v3
+    with:
+      environment: dev
+      label: Backend
+    secrets: inherit
+
+  release:
+    needs: [guard]
+    # !cancelled() so a skipped guard (e.g. non-dev push) doesn't skip release;
+    # block=true stands it down; a guard that *failed* fails closed.
+    if: ${{ !cancelled() && needs.guard.result != 'failure' && needs.guard.outputs.block != 'true' }}
+    # ...
+```
+
 ## notify — inputs
 
 Posts a rich Slack card for a pipeline result: a green/red header

From 4c6870fd9c776ee31235b82b2ffaa4f0eb0fefb0 Mon Sep 17 00:00:00 2001
From: arnavchachra <mail@arnav.ch>
Date: Wed, 15 Jul 2026 19:13:36 +0530
Subject: [PATCH 3/4] feat(empty-pr-guard): emit alert content as outputs;
 caller posts Slack

---
 .github/workflows/empty-pr-guard.yml | 78 +++++++++++++---------------
 1 file changed, 35 insertions(+), 43 deletions(-)

diff --git a/.github/workflows/empty-pr-guard.yml b/.github/workflows/empty-pr-guard.yml
index 7053ed3..5b11cd8 100644
--- a/.github/workflows/empty-pr-guard.yml
+++ b/.github/workflows/empty-pr-guard.yml
@@ -2,13 +2,15 @@ name: Empty PR-description guard
 
 # Reusable merge-time gate. On a push to a protected branch, find the PR behind
 # HEAD and, if it merged with an empty (or whitespace-only) description, revert
-# the merge, edit the PR to explain, alert Slack, and emit block=true so the
-# caller can stand its release/build/deploy jobs down (we don't ship code we're
-# reverting). This is the merge-time backstop for enforcing PR descriptions.
+# the merge, edit the PR to explain, and emit block=true so the caller can stand
+# its release/build/deploy jobs down (we don't ship code we're reverting). This
+# is the merge-time backstop for enforcing PR descriptions.
 #
 # The caller decides *when* this runs (its own `if:`, e.g. only on dev pushes)
 # and grants the token scopes; this workflow operates on whatever branch the
-# push targeted (github.ref_name) and resolves the PR from github.sha.
+# push targeted (github.ref_name) and resolves the PR from github.sha. Only
+# GITHUB_TOKEN is needed (revert + PR edit) — no secrets to pass, so this is
+# safe to call across an org boundary.
 #
 # What gets reverted depends on how the PR landed:
 #   • merge commit (>=2 parents) → `git revert -m 1` undoes the whole PR.
@@ -17,27 +19,21 @@ name: Empty PR-description guard
 #
 # Fail behaviour:
 #   • PR-fetch API error → fail SAFE: skip (block=false), never false-revert.
-#   • revert push rejected / conflicts → block stays true, Slack says "revert by
-#     hand", and the caller (which gates on this workflow's result) stands down.
+#   • revert push rejected / conflicts → block stays true, outcome reports
+#     "revert by hand", and the caller (which gates on this workflow's result)
+#     stands down.
 #
-# Secrets: the Slack webhook is typically an *environment* secret, and a job
-# that calls a reusable workflow can't declare an environment. So this workflow
-# declares the environment (from `environment` input) and the caller passes
-# `secrets: inherit`; SLACK_WEBHOOK_URL then resolves from the caller's env.
+# Slack: this workflow does NOT post to Slack. The webhook is typically an
+# environment secret, and `secrets: inherit` can't deliver an env secret to a
+# reusable workflow across an org boundary. Instead it emits the alert content
+# (outcome/header/color/reason) as outputs; the caller renders the card from a
+# job that declares the environment (see the caller's notify job).
 
 on:
   workflow_call:
     inputs:
-      environment:
-        description: >-
-          Caller environment to run under; its secrets must expose
-          SLACK_WEBHOOK_URL. Required because the webhook is an environment
-          secret and a reusable-workflow caller job cannot declare an
-          environment itself.
-        required: true
-        type: string
       label:
-        description: Short name shown in the Slack alert header (e.g. "Backend", "Web").
+        description: Short name shown in the alert header the caller renders (e.g. "Backend", "Web").
         required: false
         type: string
         default: Service
@@ -45,6 +41,18 @@ on:
       block:
         description: "'true' when the merge was reverted and the caller's release must stand down."
         value: ${{ jobs.guard.outputs.block }}
+      outcome:
+        description: "Empty when nothing was done; else reverted | push_failed | conflict."
+        value: ${{ jobs.guard.outputs.outcome }}
+      header:
+        description: "Alert header text for the caller's Slack card (empty unless the guard acted)."
+        value: ${{ jobs.guard.outputs.header }}
+      color:
+        description: "Alert colour bar for the caller's Slack card."
+        value: ${{ jobs.guard.outputs.color }}
+      reason:
+        description: "Alert status line for the caller's Slack card."
+        value: ${{ jobs.guard.outputs.reason }}
 
 permissions: {}
 
@@ -52,12 +60,15 @@ jobs:
   guard:
     name: Gate
     runs-on: ubuntu-latest
-    environment: ${{ inputs.environment }}
     permissions:
       contents: write        # push the revert commit
       pull-requests: write   # edit the reverted PR description
     outputs:
       block: ${{ steps.check.outputs.block }}
+      outcome: ${{ steps.check.outputs.outcome }}
+      header: ${{ steps.check.outputs.header }}
+      color: ${{ steps.check.outputs.color }}
+      reason: ${{ steps.check.outputs.reason }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
@@ -141,10 +152,10 @@ jobs:
                 echo "::error::Auto-revert of $SHA conflicts with later commits; manual revert needed."
               fi
 
-              # Per-outcome alert content. The Slack card itself is rendered by
-              # the notify step below (the shared notify action), which resolves
-              # the PR from github.sha for the title/link/author. We only supply
-              # the header, color bar, and Status text here.
+              # Per-outcome alert content, emitted as outputs for the caller to
+              # render (it holds the env-scoped webhook). The shared notify action
+              # resolves the PR from github.sha for the title/link/author, so we
+              # only supply the header, color bar, and status text here.
               case "$outcome" in
                 reverted)    color="#F9A825"; header=":leftwards_arrow_with_hook: ${LABEL} — merge reverted (empty description)"; reason="Merge reverted on \`${BASE_REF}\` (${rsha:0:7}); release skipped" ;;
                 push_failed) color="#D32F2F"; header=":rotating_light: ${LABEL} — revert blocked (empty description)"; reason="Revert push to \`${BASE_REF}\` rejected (branch protection); revert by hand" ;;
@@ -162,22 +173,3 @@ jobs:
           fi
 
           echo "block=$block" >> "$GITHUB_OUTPUT"
-
-      # Render the revert alert as a Slack card via the shared notify action —
-      # same card shape as the deploy announce, so both read consistently. Fires
-      # only when the guard acted (outcome set). target-sha/target-repo default
-      # to the caller's github.sha/github.repository, so notify resolves the
-      # empty-description PR for the card's title/link/author.
-      #
-      # Pinned to feat/empty-pr-guard for now (same branch as this workflow);
-      # bump to @v3 when this releases.
-      - name: Announce revert on Slack
-        if: steps.check.outputs.outcome != ''
-        uses: nurdsoft/ci-workflows/actions/notify@feat/empty-pr-guard
-        with:
-          result: failure
-          webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
-          label: ${{ inputs.label }}
-          header: ${{ steps.check.outputs.header }}
-          color: ${{ steps.check.outputs.color }}
-          status: ${{ steps.check.outputs.reason }}

From f55e586d20c6fe2faee5ce8a370be37bd2bc989c Mon Sep 17 00:00:00 2001
From: arnavchachra <mail@arnav.ch>
Date: Wed, 15 Jul 2026 19:54:21 +0530
Subject: [PATCH 4/4] docs(empty-pr-guard): sync README with outputs interface
 (no env input, caller-side Slack)

---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 40 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index ce0282e..ed212e3 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ behind a runner contract you control (or pass inline via `run`).
 | Path | Type | Function |
 |------|------|----------|
 | `.github/workflows/version.yml` | Reusable workflow | Cut a SemVer release — detects RC line, cuts the release, and creates the next RC baseline automatically |
-| `.github/workflows/empty-pr-guard.yml` | Reusable workflow | Merge-time gate — revert a merge whose PR had an empty description, alert Slack, and emit `block` so the caller stands its release down |
+| `.github/workflows/empty-pr-guard.yml` | Reusable workflow | Merge-time gate — revert a merge whose PR had an empty description and emit `block` (+ alert content) so the caller stands its release down and posts the alert |
 | `actions/auth`   | Action | Obtain cloud credentials (OIDC) |
 | `actions/setup`  | Action | Install runtime + deps (+ EAS login) |
 | `actions/verify` | Action | Lint / type-check / test |
@@ -275,28 +275,40 @@ version:
     changelog-on-rc: true
 ```
 
-## empty-pr-guard.yml — inputs
+## empty-pr-guard.yml — inputs & outputs
 
 Merge-time gate that enforces non-empty PR descriptions. Call it as the **first
 job** of your pipeline, gated to the branch you protect. On a push whose merge
 commit traces to a PR with an empty (or whitespace-only) body, it reverts the
-merge on that branch, edits the PR to explain, posts a Slack card (via
-`notify`), and sets `block=true`; wire your downstream jobs to stand down when
-`needs.<guard>.outputs.block == 'true'`. A PR-fetch API error fails **safe**
-(skips, never false-reverts); a rejected push or a revert conflict keeps
-`block=true` and the Slack card asks for a manual revert.
+merge on that branch, edits the PR to explain, and sets `block=true`; wire your
+downstream jobs to stand down when `needs.<guard>.outputs.block == 'true'`. A
+PR-fetch API error fails **safe** (skips, never false-reverts); a rejected push
+or a revert conflict keeps `block=true` and reports "revert by hand".
 
 It reverts a merge commit via `git revert -m 1` and a squash/rebase merge via
 the `before..HEAD` range, so all three GitHub merge styles are fully undone.
 
+The workflow does **not** post to Slack itself: the webhook is an environment
+secret, and `secrets: inherit` can't deliver an env secret to a reusable
+workflow across an org boundary. It needs **no secrets** (revert + PR edit use
+`GITHUB_TOKEN`), and instead **emits the alert content** as outputs — render the
+card in a caller job that declares the environment (see the example).
+
 | Input | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `environment` | string | yes | — | Caller environment to run under; its secrets must expose `SLACK_WEBHOOK_URL`. Required because the webhook is an environment secret and a reusable-workflow caller job cannot declare an environment itself. |
-| `label` | string | no | `Service` | Short name shown in the Slack alert header (e.g. `Backend`, `Web`). |
+| `label` | string | no | `Service` | Short name shown in the alert header the caller renders (e.g. `Backend`, `Web`). |
+
+| Output | Description |
+|--------|-------------|
+| `block` | `'true'` when the merge was reverted and the caller's release must stand down. |
+| `outcome` | Empty when nothing was done; else `reverted` \| `push_failed` \| `conflict`. Gate the notify job on `outcome != ''`. |
+| `header` | Alert header line for the caller's Slack card. |
+| `color` | Alert colour bar (hex) for the caller's Slack card. |
+| `reason` | Alert status line for the caller's Slack card. |
 
-Output `block` (`'true'`/`'false'`) — gate downstream jobs on it. Pass
-`secrets: inherit` so `SLACK_WEBHOOK_URL` resolves from the caller's
-environment, and grant `contents: write` + `pull-requests: write`.
+Grant `contents: write` + `pull-requests: write` on the guard job. To surface
+the alert, add a job that declares the environment holding `SLACK_WEBHOOK_URL`
+and renders the card via `notify` from the guard's outputs.
 
 ```yaml
 jobs:
@@ -305,9 +317,23 @@ jobs:
     permissions: { contents: write, pull-requests: write }
     uses: nurdsoft/ci-workflows/.github/workflows/empty-pr-guard.yml@v3
     with:
-      environment: dev
       label: Backend
-    secrets: inherit
+
+  guard-notify:                       # renders the Slack card the guard can't
+    needs: [guard]
+    if: ${{ always() && needs.guard.outputs.outcome != '' }}
+    runs-on: ubuntu-latest
+    environment: dev                  # so ${{ secrets.SLACK_WEBHOOK_URL }} resolves
+    permissions: { contents: read, pull-requests: read }
+    steps:
+      - uses: nurdsoft/ci-workflows/actions/notify@v3
+        with:
+          result: failure
+          webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
+          label: Backend
+          header: ${{ needs.guard.outputs.header }}
+          color: ${{ needs.guard.outputs.color }}
+          status: ${{ needs.guard.outputs.reason }}
 
   release:
     needs: [guard]