feat(ci): acknowledge new pull requests automatically

Contributors could not distinguish "blocked" from "ignored". Several PRs sat on green, mergeable work for over a week with no maintainer comment while release-critical work absorbed review capacity, and nothing on the PR page said so. GitHub has no repo-scoped banner for pull requests -- an org announcement banner renders only for org members, and pinned issues and discussions never appear on the PR tab -- so a comment on open is the only surface that reaches an external contributor at the moment they contribute. Posts one comment when a PR is opened, stating that it is queued, that it will not be closed for inactivity, and what genuinely speeds up review (rebased branch, green CI, one claim per PR, signed-off commits). The message lives in .github/pr-acknowledgement.md rather than in the workflow, so the status can be edited -- or acknowledgements switched off by blanking the file -- without a workflow change. A missing, empty, or whitespace-only file is the documented off switch. Uses pull_request_target because a pull_request trigger hands fork PRs a read-only token, which would fail on exactly the contributions most worth acknowledging. The job never checks out, builds, or executes PR code: checkout carries no ref and so resolves to the base commit, it is used only to read our own message file, and the PR number reaches the shell through the environment rather than string interpolation. Skips bots and owner-authored PRs. Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
2026-11-12 09:47:20 +08:00 · 2026-07-26 02:56:17 +02:00
parent 97ce23f982
commit 603e6020de
2 changed files with 101 additions and 0 deletions
@@ -0,0 +1,67 @@
+name: PR acknowledgement
+
+# Posts one acknowledgement comment when a pull request is opened, so a
+# contributor learns the current review status immediately instead of inferring
+# it from silence.
+#
+# The message text lives in `.github/pr-acknowledgement.md`. Edit that file to
+# change what is said; blank it (or delete it) to turn acknowledgements off
+# without touching this workflow. No code change is needed to switch it.
+#
+# SECURITY — this uses `pull_request_target`, which runs against the BASE repo
+# with a token that can write. That is required: a `pull_request` trigger gives
+# fork PRs a read-only token, so commenting on exactly the contributions we most
+# want to acknowledge would fail.
+#
+# The safety rule that makes it sound: this job NEVER checks out, builds, or
+# executes pull-request code. `actions/checkout` here resolves to the base
+# commit (the default under `pull_request_target`), and it is used only to read
+# the message file out of our own tree. Do not add a `ref:` pointing at the PR
+# head, and do not add a build step. Nothing from the PR is interpolated into a
+# shell command either — the body comes from a file, and the PR number is passed
+# through the environment rather than expanded inline.
+
+on:
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  contents: read
+
+jobs:
+  acknowledge:
+    runs-on: ubuntu-latest
+    # Bots do not read comments, and acknowledging our own PRs is noise.
+    if: >-
+      github.event.pull_request.user.type != 'Bot' &&
+      github.event.pull_request.author_association != 'OWNER'
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          # Base commit only — never the PR head. See the security note above.
+          persist-credentials: false
+
+      - name: Post acknowledgement
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          MESSAGE_FILE=.github/pr-acknowledgement.md
+
+          if [ ! -f "$MESSAGE_FILE" ]; then
+            echo "No $MESSAGE_FILE in the base tree — acknowledgements are off."
+            exit 0
+          fi
+
+          # An empty or whitespace-only file is the documented off switch.
+          if [ -z "$(tr -d '[:space:]' < "$MESSAGE_FILE")" ]; then
+            echo "$MESSAGE_FILE is blank — acknowledgements are off."
+            exit 0
+          fi
+
+          gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file "$MESSAGE_FILE"
+          echo "Acknowledged PR #${PR_NUMBER}."