feat: implement issue #1338 — Migrate listener-template GH_PAT_WORKFLOWS refs to GH_PAT_DON_PETRY fallback (#1326 prereq)

[don-petry]

Closes #1338

Implemented by dev-lead agent. Please review.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

@don-petry, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 50 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e0694ba0-5aac-42db-9be1-b23eb0785f50

📥 Commits

Reviewing files that changed from the base of the PR and between 298a1d2 and 8015a00.

📒 Files selected for processing (4)

• docs/aw/dependency-advisory.md
• docs/dev-lead/implementation-plan.md
• templates/gh-aw-org-listener.yml
• templates/mention-listener.yml

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev-lead/issue-1338-20260720-1830

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-07-20T19:34:32Z.

[Copilot]

Pull request overview

This PR updates the repo’s listener workflow templates (used for downstream bootstraps) to prefer the canonical org PAT secret GH_PAT_DON_PETRY while retaining GH_PAT_WORKFLOWS as a fallback, as part of the #1326 retirement path (tracked in #1338). It also updates related documentation examples so the intended token-resolution pattern is consistent.

Changes:

• Updated both listener templates to use ${{ secrets.GH_PAT_DON_PETRY || secrets.GH_PAT_WORKFLOWS }} wherever GH_PAT_WORKFLOWS was referenced bare.
• Updated documentation examples to reflect the expanded fallback chain including github.token where applicable.
• Kept docs/pr-review-agent/machine-user-setup.md unchanged (still documenting the transitional fallback), matching the stated scope.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
templates/mention-listener.yml	Replaces bare secrets.GH_PAT_WORKFLOWS with `secrets.GH_PAT_DON_PETRY
templates/gh-aw-org-listener.yml	Applies the same canonical-first fallback pattern for GH_TOKEN across issue-triage and CI-failure dispatch steps.
docs/dev-lead/implementation-plan.md	Updates example token/GH_TOKEN expressions to include secrets.GH_PAT_DON_PETRY ahead of secrets.GH_PAT_WORKFLOWS (and github.token where shown).
docs/aw/dependency-advisory.md	Updates the configuration table to document the preferred secret fallback order for GH_TOKEN.

[gemini-code-assist]

Code Review

This pull request updates workflow templates and documentation to include secrets.GH_PAT_DON_PETRY as an alternative token for GH_TOKEN. Feedback was provided regarding the limitations of fine-grained Personal Access Tokens (PATs) in multi-organization workflows, recommending classic PATs or GitHub App installation tokens if the workflow needs to span multiple organizations.

[don-petry]

Dev-Lead — fix-reviews (applied)

Changes committed and pushed.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
- Quality Gate passed with 0 new issues, 0 security hotspots, 0 coverage gaps
Files changed: None
Skipped (informational): 0
```

[donpetry-bot]

Review — fix requested (cycle 1/3)

The automated review identified the following issues. Please address each one:

Findings to fix

Automated review — NEEDS HUMAN REVIEW

Risk: MEDIUM
Reviewed commit: 8015a00cfb807ff37742eb2a24f5f498759033a0
Cascade: triage → audit (triage: haiku 4.5 → deep: opus 4.8 + duck: o4-mini → audit: fable 5)

Summary

Code-level audit found the diff safe: a mechanical, scope-exact migration of 8 bare GH_PAT_WORKFLOWS references in two listener templates to a GH_PAT_DON_PETRY-first fallback chain, plus 3 matching doc lines, precisely as specified in issue #1338. No secret values, no new injection surface, behavior identical until the new secret is provisioned, and the org-member trust gate verifiably fails closed on token error (gh api failure yields trusted=false), so misconfiguration degrades to availability loss, not a trust bypass; the mention-listener trust decision uses event-payload author_association and is token-independent. Escalating anyway: the changed tokens gate cross-org dispatch in org-wide bootstrap templates, and correct rollout depends on GH_PAT_DON_PETRY being a classic PAT with read:org and no broader scope than the token it replaces — the org secrets API returns 403 at this tier, so only a human org admin can confirm provisioning before merge.

Findings

• MINOR: GH_PAT_DON_PETRY provisioning is unverifiable from code or from this audit tier (org secrets API requires admin:org). Before merge, an org admin should confirm: (1) the org secret exists and is granted to consumer repos, (2) it is a CLASSIC PAT with read:org, (3) its scopes are not broader than GH_PAT_WORKFLOWS, since every listener step will silently prefer it once set. (templates/gh-aw-org-listener.yml:47)
• INFO: Verified the org-member trust gate fails closed: 'gh api orgs/$TARGET_ORG/members/$SENDER_LOGIN' failure (including insufficient token scope) writes trusted=false and skips dispatch. A scope-deficient GH_PAT_DON_PETRY cannot cause a trust bypass, only missed dispatches. The deep review's concern that the || fallback does not fire for a set-but-underscoped secret is correct, but the failure mode is availability, not authorization. (templates/gh-aw-org-listener.yml:52)
• INFO: mention-listener trust decision is based on github.event.comment.author_association (OWNER/MEMBER/COLLABORATOR allowlist), not on the token being migrated; the token change cannot weaken this gate. (templates/mention-listener.yml:36)
• INFO: Diff matches issue Migrate listener-template GH_PAT_WORKFLOWS refs to GH_PAT_DON_PETRY fallback (#1326 prereq) #1338 acceptance criteria exactly: 4 sites per template migrated, no new workflow_call.secrets declarations, docs/pr-review-agent/machine-user-setup.md untouched, classic-PAT requirement documented in the template header (resolves gemini-code-assist advisory). Templates are not the CLAUDE.md/AGENTS.md-restricted thin-caller stubs.
• INFO: All checks pass at head 8015a00 (CodeQL, gitleaks, ShellCheck, SonarCloud, AgentShield, Agent Security Scan). The CANCELLED 'review / review' run is superseded by a later SUCCESS run at the same SHA.

---

Reviewed by the PR-review cascade (triage: haiku 4.5 → deep: opus 4.8 + duck: o4-mini → audit: fable 5). Reply if you need a human review.

Additional tasks

1. Resolve all unresolved review thread comments from other reviewers
2. Ensure all CI checks pass after your changes
3. Rebase on the target branch if behind
4. Do NOT modify files unrelated to the findings above

The review cascade will automatically re-review after new commits are pushed.