Make post-comment marker configurable

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

.github/actions/post-comment/action.yml

@@ -1,6 +1,9 @@
 name: "Post comment"
-description: "Create, update, or delete a sticky PR comment identified by an automatically-derived HTML-comment marker. If this action is used more than once within the same job, give each step an explicit 'id:' so the derived marker stays unique."
+description: "Create, update, or delete a sticky PR comment identified by a caller-provided marker."
 inputs:
+  marker:
+    description: "Non-empty marker identifying the comment. Use a unique, stable HTML comment for each distinct comment."
+    required: true
   body:
     description: "Full comment markdown."
     required: true
@@ -26,10 +29,7 @@ runs:
       shell: bash
       env:
         BODY: ${{ inputs.body }}
-        # Derived from the workflow name, job id, and step id/sequence-number so that repeated
-        # runs of the same step find the same comment (for upsert/delete), while distinct steps
-        # (even within the same job) get distinct markers.
-        MARKER: <!-- post-comment:${{ github.workflow }}:${{ github.job }}:${{ github.action }} -->
+        MARKER: ${{ inputs.marker }}
         GH_TOKEN: ${{ inputs.token }}
         ISSUE_ID: ${{ inputs.issue-id || github.event.pull_request.number }}
         ACTION_CONDITION: ${{ inputs.action-condition }}

.github/workflows/pr-checks.yml

@@ -298,6 +298,7 @@ jobs:
           !startsWith(github.event.pull_request.head.ref, 'update-bundle/')
         uses: ./.github/actions/post-comment
         with:
+          marker: "<!-- post-comment:CHANGELOG.md -->"
           body: |
             ⚠️ `CHANGELOG.md` has been modified in this PR. Please do not modify `CHANGELOG.md` directly.
             Instead, create a change-note file in `unreleased-change-notes/`. The `CHANGELOG.md`

pr-checks/post-comment.test.ts

@@ -90,6 +90,13 @@ describe("parseOptions", async () => {
     );
   });
 
+  await it("rejects a whitespace-only --marker", () => {
+    assert.throws(
+      () => parseOptions(withFlag("--marker", " \t\n")),
+      /Missing required flag --marker/,
+    );
+  });
+
   await it("rejects an invalid --action-condition value", () => {
     assert.throws(
       () => parseOptions(withFlag("--action-condition", "yes")),
@@ -226,6 +233,33 @@ const baseOptions: Options = {
 };
 
 describe("performAction", async () => {
+  for (const action of ["upsert", "delete"] as const) {
+    await it(`uses the supplied marker for '${action}' without affecting other comments`, async () => {
+      const marker = "<!-- custom-warning -->";
+      const { client, calls } = fakeClient([
+        { id: 1, body: "<!-- marker -->\nunrelated warning" },
+        { id: 2, body: `${marker}\nold warning` },
+      ]);
+      const options = parseOptions(withFlag("--marker", marker));
+      await performAction(client, action, options);
+      assert.deepEqual(calls, {
+        createComment: [],
+        updateComment:
+          action === "upsert"
+            ? [
+                {
+                  ...options.repository,
+                  comment_id: 2,
+                  body: `${marker}\nhello`,
+                },
+              ]
+            : [],
+        deleteComment:
+          action === "delete" ? [{ ...options.repository, comment_id: 2 }] : [],
+      });
+    });
+  }
+
   await it("does nothing for 'none'", async () => {
     const { client, calls } = fakeClient([]);
     await performAction(client, "none", baseOptions);

pr-checks/post-comment.ts

@@ -10,9 +10,9 @@ The marker is passed explicitly via `--marker` and can be any non-empty string,
 HTML comment (e.g. `<!-- my-bot -->`) is recommended so it doesn't render visibly. It is used
 both to find a pre-existing comment on the pull request so that
 `upsert`/`delete` actions know which comment to operate on, and is automatically prepended to
-`--body` when posting or updating a comment so that future invocations can find it again. Callers
-typically derive this value automatically (see `.github/actions/post-comment`) rather than
-hand-authoring it.
+`--body` when posting or updating a comment so that future invocations can find it again.
+The `.github/actions/post-comment` action requires callers to supply this value via its
+`marker` input.
 */
 
 import { parseArgs } from "node:util";