fix(ci): pr-issue-linkage header misstates how the reusable reads the PR body

[kyle-sexton]

Problem

.github/workflows/pr-issue-linkage.yml's header comment says the gate is safe under pull_request_target because:

the reusable reads PR body metadata from the event payload only and runs no head code

The second half is true and is what matters. The first half is not accurate at the pinned SHA 7107b34832a7b6db5d08d3b132621c599fbe5e50 (v0.14.2), whose Load current PR body step re-fetches through the API:

gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" --jq '.body // ""'

with the event payload used only as FALLBACK_BODY if that call fails. The step's own comment calls it a "Live-refetch".

There is a further wrinkle worth settling in the same pass: verification against a live run could not find GH_TOKEN/GITHUB_TOKEN in that step's rendered environment, which would make the gh api call fail silently and the payload fallback the path that actually runs. If that holds, the behaviour matches the comment while the code does not — but neither the comment nor anything else records why. Establish which it is before rewording.

Why it matters more than a stale comment

The line immediately below carries # zizmor: ignore[dangerous-triggers] metadata-only gate; rationale in the header comment. A security suppression whose stated rationale is a sentence that does not describe the code is worth correcting even when the suppression is independently sound.

It is independently sound. Verified against the reusable at the pinned SHA: no actions/checkout step anywhere, permissions: declares only pull-requests: read and actions: read, and the body reaches actions/github-script through env:/GITHUB_ENV with a random heredoc delimiter rather than being spliced into script text. The conclusion holds; the stated basis does not.

Also in the same comment block

• "Public repo: runs on the reusable's hosted default runner." The caller pins runner: ubuntu-24.04 at the with: block. The value coincides with the reusable's default, so nothing breaks, but the stated mechanism is wrong and would not follow a change to that default.
• The no-issue marker is described as the literal "No linked issue". The constant is /\bno (?:linked|related) issue\b/i — No related issue also passes, and it is a case-insensitive regex rather than a literal. Both scans additionally run against the body with fenced and indented code blocks blanked, inline code spans masked, and HTML-commented text discarded, so a marker inside a fence does not count.

Scope note

Found while fixing #3182, whose scope was the gate-description half of this comment (a closing keyword plus ## Related, when the pinned reusable requires four sections). That half is corrected in #3183. The items above are pre-existing and were deliberately left out of that PR rather than rewritten a fourth time — #3183 went through five verification rounds, and each rewrite of this comment block introduced a new inaccuracy.

Related

• fix(docs): scope three setup-contract rules to what backs them #3183 — corrects the gate-description half; this issue is what it deliberately left alone.
• fix(docs): three rules in the merged setup-contract prose reach past what backs them #3182 — the parent issue, whose "Outside the fence" bullet first flagged this comment block.

[kyle-sexton]

[kyle-sexton]

This was generated by AI during triage.

Triage verification

Read the caller (.github/workflows/pr-issue-linkage.yml, pinned to
melodic-software/ci-workflows@7107b34832a7b6db5d08d3b132621c599fbe5e50 / v0.14.2) and the reusable
workflow's source at that exact SHA directly. All three inaccuracies described in this issue are
confirmed against the code:

1. "reads PR body metadata from the event payload only" is wrong as a mechanism claim. The
   reusable's Load current PR body step performs a live gh api repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER} re-fetch and falls back to the event payload
   (FALLBACK_BODY) only if that call fails. The step's own comment calls it a "Live-refetch."
2. The GH_TOKEN wrinkle is confirmed, not just suspected. I pulled the rendered job log for a
   real run of this workflow in this repo (run 32650374946, job 97220889596) and the Load current PR body step's logged env: block carries only PR_NUMBER and FALLBACK_BODY — no
   GH_TOKEN / GITHUB_TOKEN. gh api cannot authenticate without one of those explicitly set (the
   Actions-provided token is not implicitly picked up by gh), so the gh api call fails every time
   (stderr is redirected to /dev/null) and the fallback to the event payload is the path that
   actually runs — every observed invocation, not intermittently. So: the current effective
   behavior happens to match the original comment's claim (payload-only), but not for the reason the
   comment implies — it's a byproduct of the live-refetch attempt always failing auth, not a
   payload-only design.
3. Runner claim. The caller's with: block pins runner: ubuntu-24.04 explicitly; the reusable's
   own runner input also defaults to ubuntu-24.04. The values coincide today, but "runs on the
   reusable's hosted default runner" describes the wrong mechanism — it's an explicit pin, not
   inheritance of a default, and wouldn't track a future default change.
4. No-issue marker claim. The reusable's actual check is
   NO_ISSUE_MARKER = /\bno (?:linked|related) issue\b/i — a case-insensitive regex matching both
   "No linked issue" and "No related issue" as a word-boundary phrase, evaluated against a version of
   the body with fenced/indented code blocks blanked, inline code spans masked, and HTML comments
   stripped. Not "the literal "No linked issue"".

The independently-sound part of the existing rationale — that no head-branch code executes, so
pull_request_target is safe here — is also verified directly against the pinned reusable: no
actions/checkout step anywhere in it, permissions: there is scoped to pull-requests: read /
actions: read only, and the PR body reaches actions/github-script through env:/GITHUB_ENV with
a random heredoc delimiter, never spliced into script text. That part of the comment should be
preserved.

Agent Brief

Type: Bug
Summary: Correct the header comment block in .github/workflows/pr-issue-linkage.yml so it
accurately describes how the pinned reusable actually reads the PR body, plus two adjacent
inaccuracies in the same comment block (runner default claim, no-issue-marker claim).

Current behavior:
The header comment above the on: block states the gate is safe under pull_request_target because
"the reusable reads PR body metadata from the event payload only and runs no head code." The second
half (no head code) is accurate and verified. The first half is not: the pinned reusable's PR-body
step performs a live API re-fetch first and only falls back to the event payload if that call fails —
and in this repo's current wiring that call has no token to authenticate with, so it fails every time
and the fallback is what actually executes. The same comment block also says the workflow "runs on
the reusable's hosted default runner" (it's actually an explicit runner: ubuntu-24.04 pin that
happens to match the reusable's default) and describes the no-issue opt-out as "the literal "No
linked issue"" (it's actually a case-insensitive regex matching "no linked issue" or "no related
issue" as a phrase, masked-code-aware).

Desired behavior:
Rewrite the header comment block (and, if needed, the adjacent # zizmor: ignore[dangerous-triggers] line's implicit pointer back at it) so each claim matches the pinned
reusable's actual code:

• State plainly that pull_request_target is safe here because no head-branch code ever executes
  (no checkout of PR head, permissions scoped to read-only PR/Actions metadata, and the body reaches
  script execution only through env:/GITHUB_ENV, never spliced into script text) — keep this part,
  it is correct.
• Replace the "reads PR body metadata from the event payload only" claim with an accurate description:
  the reusable attempts a live re-fetch of the current PR body via the API and falls back to the event
  payload only if that call fails. If, at the time this is fixed, a fresh check of a real workflow run
  in this repo (or the reusable's current source, in case the pinned SHA/version has since moved)
  still shows no token wired into that step's environment, say so explicitly (effective behavior is
  payload-only today, as a side effect of the re-fetch always failing auth, not by design) rather than
  asserting the live re-fetch is what actually reads the body. Re-verify this rather than assuming the
  prior finding still holds, since either the pin or the reusable's wiring could change before this is
  picked up.
• Replace "runs on the reusable's hosted default runner" with a description naming the explicit
  runner: ubuntu-24.04 pin in the with: block.
• Replace "the literal "No linked issue"" with a description of the actual case-insensitive regex
  and its masked-code-aware evaluation (matches "No linked issue" or "No related issue" as a phrase,
  not a literal string).

Key interfaces:
None — this is a comment-only correction inside .github/workflows/pr-issue-linkage.yml. No trigger,
permission, uses: pin, or with: input changes.

Acceptance criteria:

• The header comment no longer claims the reusable reads the PR body "from the event payload
  only" as a description of its mechanism; it describes the live-refetch-with-fallback behavior
  accurately.
• The pull_request_target safety rationale (and the zizmor: ignore[dangerous-triggers] line
  pointing at it) still rests on, and accurately states, "no head-branch code executes."
• The runner claim describes the explicit runner: ubuntu-24.04 pin rather than "the reusable's
  hosted default runner."
• The no-issue-marker claim describes the case-insensitive regex (matching "no linked issue" /
  "no related issue") rather than "the literal "No linked issue"."
• No functional YAML changes: on:, permissions:, the uses: pinned SHA, and the with: block
  values are unchanged — comment text only.
• The edited workflow file still parses as valid YAML (e.g. the repo's normal workflow-lint /
  CI check for .github/workflows/** passes).

Out of scope:

• Adding a GH_TOKEN/GITHUB_TOKEN to the reusable's Load current PR body step so the live
  re-fetch actually succeeds — that step lives in melodic-software/ci-workflows, a different repo,
  and would be a behavior change, not a comment fix. File separately if wanted.
• The gate-description contract (closing keyword + ## Related/required-sections behavior) — already
  corrected in fix(docs): scope three setup-contract rules to what backs them #3183.
• Any change to .github/workflows/pr-issue-linkage.yml's triggers, permissions, or the pinned
  reusable SHA/version.

Related

• fix(docs): scope three setup-contract rules to what backs them #3183 — corrected the gate-description half of this same comment block; this issue is the half it
  deliberately left alone.
• fix(docs): three rules in the merged setup-contract prose reach past what backs them #3182 — parent issue that first flagged this comment block.

[kyle-sexton]

Taking over this work item. The previous lease was held by instance MELO-LAP-001-triage-202608230449 and expired at 2026-08-23T16:59:57Z without renewal. Worker instance melo-lap-001-worker-202608231812 is assuming the claim and will post a fresh lease marker.

[kyle-sexton]

[kyle-sexton]

This was generated by AI in the autonomous worker lane.

Review-ready pull request opened for this item: #3209 (close-linked with Closes #3184). The header now describes the pinned reusable's actual body-read mechanism (live gh api re-fetch, event-payload fallback, no token wired so the fallback is the path that runs), rests the pull_request_target rationale on "no head-branch code executes", and corrects the runner and no-issue-marker claims — comment text only, verified against the reusable source at the pinned SHA and independently reviewed.

The work-item lease held by melo-lap-001-worker-202608231812 is released. No lease is held — the item is with the merge lane via #3209.