docs(adr): add ADR 0164, run the shim on pull_request for same-repo PRs by waynesun09 · Pull Request #9227 · fullsend-ai/fullsend

waynesun09 · 2026-11-09T20:35:34Z

Summary

New ADR 0164 supersedes ADR 0009 for #9221. GitHub blocks pull_request_target by default on public repositories from 2026-12-02 (brownouts on 2026-11-09 and 2026-11-16). The shim's PR events move to pull_request, limited to same-repo PRs:

Same-repo guard, enforced twice: in the shim (head.repo.id == github.repository_id) and again in the dispatch workflow, because a fork PR runs its own copy of the shim.
Fork PRs: a maintainer comments /fs-review (issue_comment, ADR 0054 authorization unchanged). Fork PRs no longer get automatic retro.
Base checkout: dispatch checks out the base commit for pull_request, as it already does for pull_request_target and pull_request_review.
Old callers: pull_request_target is still accepted, with a warning.
Rollout: a required change in the next release.

ADR 0009 is not edited: no status flip, no notes. Living docs updated: docs/architecture.md (shim security bullet, marked target state; code agent runtime) and docs/problems/gitlab-implementation.md (an annotation on the GitHub line).

The implementation is in a separate PR (follows).

Evidence for current behaviour (fullsend `96e0c4338`)

internal/scaffold/fullsend-repo/templates/shim-per-repo.yaml: the shim triggers on issues, issue_comment, pull_request_target, pull_request_review, and passes repository secrets to reusable-dispatch.yml via workflow_call.
.github/workflows/reusable-dispatch.yml: the checkout ref is base.sha for pull_request_target and pull_request_review, and github.sha otherwise.
internal/mintcore/claims.go ValidateWorkflowRef: job_workflow_ref must name an allowed workflow host repository.
internal/harnessdispatch/auth.go IsLifecycleCloseAuthorized: checks RawType == "pull_request_target".

External references

GitHub changelog, 2026-11-02: pull_request_target blocked by default December 2. The first notice was the 2026-09-17 post on workflow execution protections; its date was edited from 2026-11-02 to 2026-12-02 on 2026-10-21.
GitHub docs: Securely using pull_request_target.
gh-aw at 62ddc3a8: on: pull_request compiles to a job guard head.repo.id == github.repository_id (pkg/workflow/filters.go). forks: defaults to same-repo (#72579). Both pull_request and pull_request_target are limited to same-repo PRs by default (BuildNotFromFork, pkg/workflow/expression_builder.go); fork PRs are admitted through a forks: allowlist or author association.

Review

Decision check, Gemini 4 Argon: PROCEED, no changes.
Prose check, Gemini 3.8 Flash: defined "shim", "brownout", "mint" and "retro" on first use, fixed the table caption, and cut Consequences to 5 bullets. Each edit was verified before it was applied.
make lint passes.

Refs #9221

🤖 Generated with Claude Code

qodo-code-review · 2026-11-09T20:36:47Z

PR Summary by Qodo

Document same-repo pull_request dispatch in ADR 0164

📝 Documentation 🕐 10-20 Minutes

AI Description

• Supersede ADR 0009 with a plan to preserve automatic review after GitHub restricts
 pull_request_target.
• Specify two same-repo guards, base-commit checkout, and maintainer-triggered review for fork PRs.
• Update living documentation; the workflow and CLI implementation will follow separately.

Diagram

graph TD
  A["PR event"] --> B{"Same repo?"} -->|Yes| C["Shim dispatch"] --> D{"Dispatch guard"} -->|Allowed| E["Base checkout"] --> F["Review and retro"]
  B -->|Fork: manual review| G["Maintainer comment"] -->|Authorized| D
  D -->|Fork PR event| H["No stage"]

High-Level Assessment

The following are alternative approaches to this PR:

1. Allow pull_request_target by event policy

➕ Preserves automatic review of fork PRs.
➕ Requires less change to the existing trigger model.
➖ Requires every adopting repository or organization to maintain a policy exception.

2. Authorize through a hosted webhook receiver

➕ Could restore automatic fork review without relying on pull_request_target.
➖ Requires a new hosted service and cannot meet the stated rollout deadline.

Recommendation: The ADR’s same-repo trigger and independently enforced dispatch guard are the pragmatic choice for the deadline, provided the base checkout and dispatch changes ship together with the shim. Consider a webhook receiver separately if automatic fork review becomes a requirement.

Files changed (3) +137 / -3

Documentation (3) +137 / -3

0164-run-the-shim-on-pull-request-for-same-repo-prs.mdRecord the replacement PR-trigger security decision +134/-0

Record the replacement PR-trigger security decision
• Adds accepted ADR 0164, superseding but not editing ADR 0009. It documents the planned same-repo guards, manual fork-review path, base checkout, legacy-caller warning, rollout, alternatives, and consequences.
docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md

architecture.mdDescribe the target shim security model +2/-2

Describe the target shim security model

• Replaces the architecture overview’s pull_request_target security description with ADR 0164’s explicitly marked target state. It also changes the code-agent runtime description to identify same-repo pull_request events as the planned automatic review trigger.

docs/architecture.md

gitlab-implementation.mdMark the GitHub shim comparison as superseded +1/-1

Mark the GitHub shim comparison as superseded
• Annotates the historical pull_request_target description with a link to ADR 0164 and its same-repo pull_request decision. The GitLab security discussion remains unchanged.
docs/problems/gitlab-implementation.md

fullsend-ai-review · 2026-11-09T20:37:41Z

🤖 Review · ⚠️ Cancelled · Started 8:37 PM UTC · Ended 8:48 PM UTC

Commit: 9fdf0ec · View workflow run →

This review was superseded by a newer commit. Check the current pull request HEAD's review status before merging.

qodo-code-review · 2026-11-09T20:43:25Z

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (2)

1. ~~Docs call an unshipped trigger live~~ ✓ Resolved

Resolving commit: 093558f

Resolution reason

At PR head, docs/architecture.md line 797 now reads "Review dispatch is triggered automatically by
pull_request_target events today; the decided target state is same-repo pull_request events (ADR
0164)." This explicitly keeps the current pull_request_target trigger as current behavior and labels
pull_request as target state. The gitlab-implementation.md shim note (line 1273) is likewise marked
"Superseded by ADR 0164, target state". The shim-security bullet in architecture.md (line 59) also
labels the change "target state". The issue is resolved in the current content.

Description

The code agent runtime entry in docs/architecture.md and the shim note in
docs/problems/gitlab-implementation.md describe same-repo pull_request review dispatch as
already active rather than as a target state. Until the separate implementation PR lands, the
installed shim still listens on pull_request_target, so readers checking the current review
trigger and security posture are given the wrong workflow.

2. Upgrade guide skips credential effects 📎 Requirement gap ⚙ Maintainability

Description

The Consequences section describes fork-PR, retro, and Dependabot effects but says nothing about how
inference credentials or review publication change once the shim moves to pull_request. Consumers
planning the upgrade therefore cannot tell whether their inference setup or where reviews appear
will change.

Code

docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[R120-122]

+- Repositories that take the release keep automatic review and retro for
+  same-repo PRs after 2026-12-02; public repositories that do not upgrade lose
+  both, while `/fs-*` commands, triage and the fix loop keep working.

Relevance

●● Moderate
Migration-guidance gap is rule-based; no close precedent found for credential or review-publication
effects.
PR-#8158

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Rule 4444013 requires migration guidance that covers fork PRs, inference credentials, and review
publication. The Consequences bullets cover retro, /fs-review, and Dependabot only.
Deliver changes and consumer migration guidance
docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[118-131]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The migration guidance in the ADR's Consequences does not cover inference credentials or review publication, which rule 4444013 requires alongside fork PR effects.

## Fix Focus Areas
- docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[118-122]

## Recommended Fix
Add bullets stating whether same-repo `pull_request` runs get the inference credentials used today, and where automatic review comments are published for same-repo and fork PRs.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

3. ADR background runs long before options 📜 Skill insight ⚙ Maintainability

Description

The Context section has a long opening paragraph, a two-bullet change list, a table introduction,
and two further paragraphs, well beyond three short paragraphs. It also restates permission and
secret analysis inline rather than linking to the problem docs, which delays the rationale before
Options.

Code

docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[R58-61]

+gh-aw, GitHub's own agentic workflow tooling, made the same move: plain
+`pull_request` limited to same-repo PRs by default, with fork PRs handled only
+after a maintainer's slash command
+([github/gh-aw#72579](https://github.com/github/gh-aw/pull/72579)).

Relevance

●● Moderate
Earlier ADR Context-length findings were rejected (PR 2582), but that precedent is older than three
months and only loosely matches.
PR-#2582
PR-#2650

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The Context section contains more than three paragraphs plus bulleted and tabular blocks, which the
rule does not allow.
docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[23-66]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Context section of ADR 0164 has far more than three short paragraphs and restates the permission and secret analysis inline. The rule requires 1-3 short paragraphs that link to problem docs.

## Fix Focus Areas
- docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[23-66]

## Recommended Fix
Reduce Context to at most three short paragraphs. Move the per-author permission table and the gh-aw detail into a linked reference or the Options section, and keep the bullets on what changed, linking to the relevant ADRs.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

4. ~~Old ADR 0009 lacks a superseded pointer~~ ✗ Dismissed

Description

Supersedes in ADR 0164 points at ADR 0009, but ADR 0009 is left unedited with no Superseded by
reference. A reader of ADR 0009 still sees its decision as Accepted and has no link to the
replacement, which the supersession rule requires.

View medium (3)

5. ~~A behaviour claim has no source link~~ ✓ Resolved

Resolving commit: 001f3c2

Resolution reason

The PR head content now cites "(since [#264](https://github.com/fullsend-ai/fullsend/pull/264))"
directly after the pull_request_review trigger claim in the same-repo row, providing the
provenance link the finding requested.

Description

The same-repo row of the Options table states that the shim's pull_request_review trigger already
runs the PR branch's copy today, with no link to the ADR or PR that introduced that trigger. The
shim template confirms the trigger exists, but a file path is not a provenance link to the
introducing change.

6. ~~Upgrade readiness is claimed, not shown~~ ✗ Dismissed

Description

The Options table marks option B as working by 2026-12-02, but the ADR records no validation of the
new trigger under the restriction and no readiness check for the 2026-11-16 brownout. The PR's `make
lint` and model review checks do not establish runtime behaviour under the restriction.

7. Affected automation has no owner list 📎 Requirement gap ⚙ Maintainability

Description

The ADR's Rollout section names only the shim re-render through fullsend repos install and
identifies no shared workflows, generated callers, or automatic review paths that depend on
pull_request_target, nor their responsible maintainers. Maintainers cannot tell which consumers
must upgrade, and the Dependabot case noted in Consequences is left without an owner.

Code

docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[R104-107]

+6. **Rollout.** The new shim ships as a required change in the next fullsend
+   release, together with the dispatch and CLI changes, so no repository can
+   run the new shim against a dispatch that would check out PR code.
+   Repositories receive it through their normal upgrade (`fullsend repos

Relevance

●● Moderate
Requested owner/inventory section is rule-driven; no close precedent in history to decide either
way.
PR-#8158

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Rule 4444010 requires an inventory of affected automation and owners. The Rollout section lists no
such inventory, and the Dependabot effect appears only as a runtime consequence.
Inventory affected PR automation and owners
docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[104-107]
docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[129-131]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR does not inventory the shared workflows, generated caller shims, and automatic review paths that depend on `pull_request_target`, and it names no responsible maintainers for them.

## Fix Focus Areas
- docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[104-107]
- docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[129-131]

## Recommended Fix
Add a section listing each affected shim, generated caller, and automatic review path, with its owning maintainer or administrator and its migration step. Include the Dependabot case explicitly.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

8. One ADR records six separate decisions 📜 Skill insight ⚙ Maintainability

Description

The Decision section lists six numbered items, including the old-caller warning and the release
rollout, which are independent choices that could be accepted or reversed separately. The rule
requires one decision per ADR, so these items would need to be split into separate ADRs.

Code

docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[R83-85]

+1. **Trigger.** The shim listens to `pull_request` with the types it uses
+   today (`opened`, `synchronize`, `ready_for_review`, `closed`, `labeled`,
+   `unlabeled`). It no longer lists `pull_request_target`.

Relevance

● Weak
The author explicitly dismissed the same finding type (one ADR bundling multiple decisions) as
intentional in a very recent PR.
PR-#8679

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The Decision section has six numbered items that each state a separate decision, including backward
compatibility for pull_request_target and release sequencing, which the rule treats as more than
one decision.
docs/ADRs/0164-run-the-shim-on-pull-request-for-same-repo-prs.md[83-108]
Skill: writing-adrs

Dismiss ↗ | View ↗

Context sources

❌ Tickets: failed to load — Ticket collection could not establish complete evidence

✅ Compliance rules (platform): 96 rules

✅ Skills: 5 invoked

writing-user-docs

writing-adrs

check-patch-coverage

cutting-releases

adr-corner

✅ Web pages:

🌐 Securely using pull_request_target

🌐 Events that trigger workflows

🌐 content/actions/reference/workflows-and-actions/workflow-syntax.md

+7 more

✅ Cross-repo context — repo relationships

Explored: repo: fullsend-ai/experiments (sha: d4292120) — View relationship

Explored: repo: fullsend-ai/.fullsend (sha: 5e159214) — View relationship

Explored: repo: fullsend-ai/metrics (sha: def2a969) — View relationship

Explored: repo: fullsend-ai/agents (sha: 82226d2a) — View relationship

Explored: repo: fullsend-ai/mlflow-assessments (sha: 0058f877) — View relationship

Explored: repo: fullsend-ai/test-creator (sha: a5082d20) — View relationship

Explored: repo: fullsend-ai/pi-anthropic-vertex (sha: d2ecd039) — View relationship

Explored: repo: fullsend-ai/pi-xai-vertex (sha: a86139bf) — View relationship

Explored: repo: fullsend-ai/org (sha: b5735c32) — View relationship

Explored: repo: fullsend-ai/devlake (sha: ba0670f2) — View relationship

✅ REVIEW.md

Review mode: Auto: ⚖️ Balanced: Markdown-only, but it defines a security-sensitive shim authorization design; not skip, not extended.

Tip of the day

💡 Did you know, you can move or hide resolved findings to focus on what still needs action

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

fullsend-ai-review · 2026-11-09T20:47:57Z

🤖 Finished Review · ⚠️ Cancelled · Started 8:37 PM UTC · Completed 8:47 PM UTC

Commit: 9fdf0ec · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $2.03

This review was superseded by a newer commit. Check the current pull request HEAD's review status before merging.

fullsend-ai-review · 2026-11-09T20:49:54Z

🤖 Review · ⚠️ Cancelled · Started 8:49 PM UTC · Ended 8:51 PM UTC

Commit: 5b211d1 · View workflow run →

This review was superseded by a newer commit. Check the current pull request HEAD's review status before merging.

fullsend-ai-review · 2026-11-09T20:53:17Z

🤖 Finished Review · ✅ Success · Started 8:53 PM UTC · Completed 9:03 PM UTC

Commit: 093558f · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.94

github-actions · 2026-11-09T20:56:26Z