Carlos Florêncio
89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
---
|
|
status: current
|
|
system: integrations
|
|
requirements:
|
|
- REQ-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001
|
|
created: 2026-09-23
|
|
updated: 2026-09-23
|
|
owners:
|
|
- kandev
|
|
---
|
|
|
|
# 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](../../workspaces/system-design/worktree-base-refresh.md)
|
|
continues to own repository-qualified PR preparation.
|
|
|
|
| Acceptance criterion | Design section |
|
|
| --- | --- |
|
|
| `AC-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001.1` | [Identity and auto-start token](#identity-and-auto-start-token) |
|
|
| `AC-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001.2` | [Automated launch gates](#automated-launch-gates) |
|
|
| `AC-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001.3` | [Manual start](#manual-start) |
|
|
| `AC-INTEGRATIONS-GITHUB-FORK-REVIEW-START-001.4` | [Manual PR-link creation](#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](../../../decisions/2026-09-23-fork-pr-review-watch-manual-start.md)
|
|
records why the watcher leaves fork tasks idle and why provider identity alone
|
|
does not authorize execution.
|
|
|
|
## Identity and auto-start token
|
|
|
|
`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 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.
|
|
|
|
## Related decisions
|
|
|
|
- [Fork PR review watch manual start](../../../decisions/2026-09-23-fork-pr-review-watch-manual-start.md)
|
|
- [Repository secrets](../../../decisions/2026-08-03-scope-and-merge-repository-secrets.md)
|