Review and approve a Defend pull request

Outcome

You have turned a generated patch into a GitHub pull request using the two-step request → approve flow, and you can track the PR's state (open, merged, closed) from inside prpl.

Who can do it

Opening a PR is deliberately split into two separately permissioned actions, so the person who generates patches does not have to be the person allowed to write to your GitHub repository:

• Step 1 — 1 · Request PR requires the patch.generate capability. It records intent only; nothing is pushed.
• Step 2 — 2 · Approve & open PR requires the patch.pr.approve capability. This is the only step that pushes a branch and opens the pull request on GitHub.

Both actions are limited to the run's owner, a site admin, or an organization member holding the capability for that repository's organization. An owner can grant the two capabilities to different members — see Roles and permissions.

Before you begin

• A completed Defend run with a generated patch — see Generate and review patches with Defend. Read the patch evaluation before requesting a PR.
• The approver needs a GitHub token that can push to the repository. If you connected GitHub already (Connect GitHub authentication), that saved token is reused automatically and the form says saved token — no paste needed. A pasted token needs repo scope (classic) or Pull requests: Read and write (fine-grained) and is kept only for your browser session.
• The push creates a branch named prpl/defend/… against the same commit the patch was generated on.

Steps

1. Open the defend result page — from the finding row's defend ✓ link, the Patch & PR → button on the finding, or the run list at /jobs.
2. Expand Open this patch as a GitHub PR beneath the patch evaluation.
3. Click 1 · Request PR. The caption reads records intent — no push yet; the page confirms with "PR requested — awaiting approval (patch.pr.approve)."
4. The approver (anyone holding patch.pr.approve for the repository) opens the same panel, leaves the GitHub token field blank to reuse the saved token (or pastes one), optionally sets branch suffix (optional), and clicks 2 · Approve & open PR.
5. On success the banner "PR opened on GitHub." appears and the panel is replaced by the PR block: the PR number (linked), its state badge, and the prpl/defend/… branch and base branch. Use ↻ refresh to re-fetch the live state from GitHub.
6. Review and merge the pull request on GitHub with your normal review process — prpl never merges for you.

Verify

• The defend result shows the PR block with #N and state open, and the same PR exists on GitHub from a prpl/defend/… branch.
• The finding row on the repository page gains a PR #N · open pill; after merging, ↻ refresh shows merged.
• The Needs your decision action center tracks the open PR until it is merged or closed.

Troubleshooting

• "Request a PR first (step 1) before it can be approved." — the approval was clicked without a pending request; complete 1 · Request PR first.
• "GitHub token was rejected — check that the PAT is current" (401) — the token expired or was revoked; paste a fresh one.
• "GitHub token lacks the required scope" (403) — fine-grained tokens need Pull requests: Read and write; classic tokens need full repo scope.
• "branch already exists with different content, or git apply rejected the patch" (409) — if an earlier attempt already pushed the branch, retry without a branch suffix and the PR call reuses it.
• "GitHub refused the PR (already exists, no diff, or branch protection)" (422) — check for an existing PR from the same branch and your repository's branch-protection rules.
• Nothing to request — the panel only renders when the Defend run produced a patch; a fail patch run has no PR panel. Relaunch Defend first.

Next steps

Keep coverage continuous with Schedule recurring scans, and tidy completed work with Archive scans, findings, and history.