GitHub fork review task start design

Ownership and mapping

The integration system owns GitHub review-watch task creation and its provider-specific auto-start decision. The task system owns task persistence. The workspace worktree design continues to own repository-qualified PR preparation.

Acceptance criterion	Design section
`AC-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001.1`	Identity and auto-start token
`AC-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001.2`	Automated launch gates
`AC-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001.3`	Manual start
`AC-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001.4`	Manual PR-link creation

Trust boundary

A fork PR head controls files read by repository setup commands such as package install scripts. Those commands run before the agent starts and can receive executor-profile environment values. Provider validation proves the head identity and target relationship; it does not establish trust in the source code.

The manual-start decision records why the watcher leaves fork tasks idle and why provider identity alone does not authorize execution.

Identity and auto-start token

CheckReviewWatch receives lightweight PRs from GitHub search and enriches untracked results with GetPR before publishing review events. Enrichment must carry the full response's head and base repository identity, head and base revisions, mergeability details, and maintainer modification permission alongside the existing branch and diff fields. A PR with branch names but no head repository identity still needs enrichment. If the detail fetch fails or the provider has no head identity, the event retains incomplete identity and the launch decision remains fail-closed. Search-result target identity remains the repository used to look up the PR.

buildReviewTaskRequest compares the PR head owner and repository name with the target owner and name using case-insensitive GitHub identity. If both identities are present and equal, it creates the normal one-shot auto-start token. If the head differs or either identity is missing, it persists fork_pr_requires_manual_start and does not create that token. The permanent auto-start guard remains so competing watcher and workflow paths cannot bypass the decision.

The check does not alter checkout_branch, base_branch, PR association, comparison target, contribution binding, or Git push configuration.

Automated launch gates

The task metadata marker is checked before deferred workflow launch and at the central automatic StartTask boundary. Review-watch and workflow auto-start paths leave the task available without preparing a worktree or running setup. The central check protects other automated callers that reach StartTask directly. A missing marker preserves existing behavior.

The marker is durable for the task. Manual launch does not clear it, so later background automation remains blocked. This avoids converting one user action into ongoing approval for future unattended runs.

Manual start

A direct user start uses the existing non-automatic task launch path. It is not blocked by fork_pr_requires_manual_start, so no approval screen, setting, or new API field is required. The existing task state and PR association remain available while the task waits.

Manual PR-link creation

Browser PR-link creation is a user-submitted task flow rather than a review watch. It does not carry the review-watch marker. Existing explicit task creation and launch behavior therefore remains unchanged for fork PR links.

Verification

Backend tests cover search-result enrichment through review event creation, same-repository auto-start tokens, fork and missing-head identity suppression, both review-watch auto-start paths, rejection at the central automatic launch boundary, and successful manual start. Existing browser tests continue to prove manual PR-link launch from a fork head.

4.5 KiB Raw Permalink Blame History