Feat: Gate fork PR transfer on maintainer approval

[ModeSevenIndustrialSolutions]

Closes #383

Completes the fork-handling work started in #384 and #382. Transferring a fork
pull request pushes someone else's code into Gerrit under the tool's SSH
identity, where Gerrit CI then executes it. Nothing required a maintainer to
have looked at it first.

Scope

The gate applies to unattended runs where the tool cannot positively establish
that the head lives in the base repository.

Same-repository pull requests skip it: pushing a branch to the base repository
already implies write access, and Dependabot, pre-commit.ci and Copilot all work
that way, so automation-only consumers never meet it. That is why it defaults to
on with no new input.

Direct CLI invocation also skips it. The operator chose the pull request and is
using their own credentials, so they are already the authority the gate looks
for.

Everything else — forks, and pull requests whose provenance the tool cannot
establish — needs approval. This uses head_is_trusted rather than
is_fork_pr: the former answers the authorisation question and reports False
when provenance is unknown, which is the distinction #384 introduced.

Why reviews rather than comment directives

On a Gerrit mirror the only usable trust signal is organisation membership. The
opendaylight/mdsal collaborator list is entirely LF infrastructure staff and
bots, while project committers appear only as MEMBER — so requiring write or
admin would trust the wrong people and exclude the right ones.

But the pull request author frequently holds that same membership. Under a
comment scheme they could authorise their own change. GitHub structurally
forbids approving your own pull request, so a review carries a guarantee a
comment cannot. That is the whole argument, and it is why the author is also
excluded locally — the structural check is doing most of the work.

What counts as approval

An approving review where every one of the following holds:

• the reviewer's author_association is in the trusted set (shared with PR comment commands accept directives from any user #382
  via trust.py);
• the review targets the current head commit;
• no trusted reviewer has since requested changes; and
• the reviewer is not the pull request author.

Binding to the head SHA is essential. GitHub keeps approvals across pushes
unless branch protection dismisses them, so an unbound approval would let a
contributor gain approval for one revision and push another. Maintainers
re-approve after each push, which is the correct trade. Absent SHA metadata on
either side withholds approval rather than skipping the comparison.

The binding survives the fetch. The gate reads the head SHA from the API,
while the workspace fetch reads the mutable refs/pull/<N>/head. The tool
records the approved commit and refuses anything else after fetching, so a push
timed against a running workflow cannot slip an unreviewed commit into Gerrit.
That refusal fails loudly, unlike an ordinary block, because it falls outside the
normal course of events.

Reviews arrive as history, not current state, so the evaluation reduces to
each author's latest position. COMMENTED and PENDING express no position and
must not displace an approval. DISMISSED must — my own test caught that it
originally did not, leaving a revoked approval still authorising the transfer.

Placement and failure behaviour

The gate runs before the tool fetches anything from the pull request and before
the Gerrit key is materialised, on both the single-PR and bulk paths.

Every failure path refuses: unreadable reviews, an unresolvable pull request, a
missing GITHUB_TOKEN, and absent SHA metadata all block. The token case
mattered — _extract_and_display_pr_info returns early without one, so placing
the gate inside it would have failed open exactly when the environment is least
well configured.

pull_request_review support

pull_request_target carries no event for a submitted review, so approving
would otherwise do nothing. Callers need:

on:
  pull_request_target:
    types: [opened, reopened, edited, synchronize, closed]
  pull_request_review:
    types: [submitted, dismissed]

The event maps to UPDATE, and a review-triggered run on an untrusted head
authorises the create-missing fallback. Both halves are needed:

• a review changes no code, so an existing change should gain a patchset rather
  than a sibling — mapping to CREATE would raise a duplicate on every
  re-approval after a push;
• but the review may equally be the event that first unblocks the pull
  request, when no Gerrit change exists — UPDATE alone hard-fails there, at
  core.py:1768, and only after the fork has been fetched and the key unlocked.

Scoped to untrusted heads so a review on a same-repository pull request cannot
quietly override CREATE_MISSING=false.

action.yaml needs no change: PR number and PR_HEAD_REPO both resolve from
the pull_request_review payload, and _augment_pr_refs_if_needed (#384) fills
the refs GitHub leaves empty on that event.

When the gate blocks

The run finishes successfully. A pull request waiting for a human is not
broken, and a red check would suggest otherwise — this follows the existing
G2G_DISABLED precedent of exiting cleanly with a message.

One comment explains what is missing, and later runs edit it rather than adding
another. Ownership of that comment is established by attempting the edit,
which the API refuses on another user's comment — the marker alone is not proof
of authorship, since anyone may paste it. A stale approval is reported as stale,
so a maintainer who did approve is not told that nobody has.

A note on the self-test

Test GitHub Action failed on the first push of this branch, and the reason is
worth recording: pull requests to this repository come from a fork, so the gate
blocked the action's own deliberate-failure test, which then exited successfully
having transferred nothing. The gate working as designed. That assertion is now
skipped for fork pull requests, which is honest about what can be tested from
one.

Validation

• uv run pytest tests/ — full suite passes, coverage 72.30%
• tests/test_fork_approval_gate.py covers trusted and untrusted associations,
  head-SHA binding including the approve-then-push bypass and absent metadata,
  self-approval, the history reduction (supersession, trailing comments,
  dismissal, pending), the fail-closed paths, comment ownership against a
  planted marker, the post-fetch head comparison, per-PR recording hygiene in
  bulk runs, gate scoping, and the review-event operation mode
• prek run --all-files, zizmor --persona auditor (no findings), aislop
  (score 100, zero findings)

Follow-up

• Global base-path cache leaks between tests #385, Duplicate detection cannot distinguish derived config #386 — unrelated cleanup, neither blocking

This changes no repository's behaviour on its own: AUTOMATION_ONLY still
defaults to true and closes human pull requests before the gate is reached. A
project accepting user submissions sets that to false, at which point this
becomes the control.

[Copilot]

Pull request overview

Adds maintainer-approval gating before fork PRs transfer to Gerrit.

Changes:

• Evaluates trusted reviews against the current head SHA.
• Supports review-triggered updates and create-missing fallback.
• Adds gate documentation and tests.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/github2gerrit/pr_approval.py	Implements approval evaluation and notices.
src/github2gerrit/cli.py	Integrates gating into transfer paths.
src/github2gerrit/core.py	Handles review-triggered creation fallback.
src/github2gerrit/models.py	Maps review events to updates.
src/github2gerrit/github_api.py	Adds review API abstractions.
tests/test_fork_approval_gate.py	Tests gate behavior.
docs/features.md	Documents approval gating.

Suppressed comments (1)

src/github2gerrit/cli.py:301

• The approval is checked against the PR API snapshot, but that SHA is not carried into the checkout. _prepare_workspace_checkout later fetches the moving refs/pull/<N>/head, so the author can push a new commit between this check and the fetch and this run will transfer code that was never approved. Carry the approved head SHA into the checkout and fail closed unless the fetched/archive commit exactly matches it (or fetch the exact approved SHA).

    status = evaluate_fork_approval(
        pr_obj, head_sha=head_sha, author_login=author
    )

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (1)

src/github2gerrit/models.py:163

• Mapping every submitted review to UPDATE still resubmits approved fork PRs on non-approval reviews. After a fork head has one valid approval, COMMENTED is deliberately ignored by the history reducer, so any outsider can submit another comment-only review; the gate remains approved and the unchanged head runs through the Gerrit update pipeline again. Preserve the triggering review state and only continue the transfer for an APPROVED submission; dismissal/change-request events can still evaluate and update the gate notice, but should stop when another approval leaves the gate open.

        if self.event_name == "pull_request_review":
            return PROperationMode.UPDATE