PRACTICAL GUIDE · GITHUB CODE REVIEW

Risk-based pull-request review for GitHub teams

A typo fix and an authentication change need different attention. Risk-based review lets your team choose how much human review a change needs, then find people who know the code and are available to review it.

By TriagePilot · Reviewed 25 October 2026 · Product behavior: v1.1.1

This guide is published by TriagePilot. Product claims follow the versioned documentation linked below. The configuration uses illustrative paths and user handles; it does not describe a customer deployment.

Define what makes a change risky

Start with the changes your team wants people to examine closely: authentication, payment logic, database migrations, or a large change across many files. Agree on these cases before choosing thresholds. A risk score applies your policy; it does not prove that code is safe or replace a person’s judgment.

TriagePilot provides self-hosted, risk-based pull-request routing for GitHub. In .triagepilot.yml, you can set risk thresholds, give sensitive paths extra weight, cap documentation-only scores, and mark large changes as high risk. Reaching either configured size limit marks the change high risk after test files are excluded.

Keep risk and ownership rules together so reviewers can see why a change needs attention and who is eligible to review it. TriagePilot reads the configuration from the trusted base revision. An unmerged pull request cannot enable enforcement for itself.

Choose whom to ask, then check approvals

TriagePilot requests no human reviewer for low-risk changes, one for medium risk, and one by default for high risk. Set routing.high_risk_reviewers: 2 to request two for high-risk changes. Those are the only supported high-risk counts; TriagePilot never requests more than two people for one decision.

Matching owners come first. Configured fallback reviewers can fill remaining slots, and the pull-request author is excluded. Centrally administered availability schedules narrow that eligible pool. If too few people are eligible, TriagePilot records the shortfall and requests only the available reviewers. It does not invent additional owners.

Reviewer selection and approval enforcement are separate. In enforce mode, triagepilot/human-review-policy checks the risk-dependent human-approval count: zero for low risk, one for medium, and the configured one or two for high risk. Any active individual approval counts, including one from a person who was not selected. Bot reviews do not count. A later dismissal or request for changes from that reviewer removes the approval; a new commit alone does not cause TriagePilot to discard active approvals or re-request review.

GitHub blocks merging on this policy only when an operator makes the check required. A human-review route with no eligible individual reviewer fails the check; a shortage does not lower the approval count. CI and other merge requirements remain separate.

What can GitHub handle on its own?

If path ownership and a fixed approval count meet your needs, GitHub’s native controls may be enough. Use a separate routing policy when you need reviewer selection and approval counts to depend on change risk. The reviewer-assignment guide compares manual requests, CODEOWNERS, team assignment, and custom automation in more detail.

Scroll horizontally to compare the controls on a narrow screen.

Ownership, reviewer requests, and merge requirements solve different problems
Control	What it does	What to configure separately
GitHub CODEOWNERS	Maps paths to users or teams and requests owners.	Require owner approval in GitHub. It does not score risk or balance reviewer workload itself.
GitHub team auto-assignment	Chooses a configured subset when a team is requested, with round-robin or load-balancing options.	Approval requirements. Team assignment does not provide TriagePilot’s configurable change-risk model.
GitHub rulesets	Require approvals, owner reviews, or checks before merging.	A source for a custom risk-dependent check. The native numeric approval requirement is fixed for the applicable rule.
TriagePilot v1.1.1	Combines risk, ownership, workload, and availability to select reviewers; publishes a separate human-review policy in enforce mode.	Self-hosting, individual ownership handles, App permissions, and a GitHub ruleset requiring the policy check.

TriagePilot does not import CODEOWNERS. Its ownership rules accept individual GitHub handles, not organization team handles. You can retain CODEOWNERS and GitHub owner-review requirements alongside it, but maintain both policies and evaluate their combined effect.

See GitHub’s team review settings and ruleset reference for native behavior and plan availability.

Try the policy without sending review requests

After completing the self-hosting and GitHub App setup, put this example in .triagepilot.yml at the repository root. Replace the example handles with real eligible users and choose paths that match your repository. Keep mode: shadow while evaluating.

version: 1
mode: shadow
routing:
  high_risk_reviewers: 2
risk:
  size:
    high_changed_files: 100
    high_changed_lines: 5000
  thresholds:
    low: 25
    high: 70
  paths:
    - pattern: "src/auth/**"
      weight: 30
      tag: auth
  suppressors:
    - if_all_match: ["docs/**", "*.md", "*.mdx"]
      ceiling: 25
ownership:
  rules:
    - paths: ["src/auth/**"]
      reviewers: ["@alex", "@sam"]
  fallback_reviewers: ["@alex", "@sam"]

The example sets high-risk routing to two people, adds weight for authentication paths, and caps documentation-only scores. A path weight of 30 contributes to the score; it does not by itself guarantee a high-risk tier. Compare the resulting decisions with your expectations before changing thresholds.

With no branch exclusions, the example can evaluate pull requests targeting your default branch. Draft pull requests are skipped by default. Availability schedules live in the administration interface and PostgreSQL, outside this YAML file.

Shadow mode reads GitHub data and records decisions locally, with no reviewer requests, labels, or checks written to GitHub. You still need a running application, worker, database, and GitHub App. Missing configuration also defaults to shadow mode; invalid effective configuration records a failure and performs no write.

Evaluate before making the check required

Choose representative changes. Include routine edits, sensitive paths, large changes, an absent owner, and a case with too few eligible reviewers.
Inspect recorded decisions. Check the risk tier, zero/one/two reviewer distribution, ownership matches, fallbacks, and availability exclusions. Record disagreements and adjust the policy.
Prepare enforcement. Review App permissions and review-event subscriptions. Merge a trusted repository configuration using mode: enforce only after the shadow decisions match your policy.
Configure GitHub deliberately. Follow the human-review policy guide: require triagepilot/human-review-policy from the TriagePilot App. Its documented setup uses native required approvals of zero so the conditional check supplies the count. Retain the CI, security, and owner-review requirements your team needs; a separate fixed approval minimum still applies if you keep one.
Test merge behavior and rollback. Confirm insufficient approvals block merging and qualifying individual approvals satisfy the check. Check that other requirements still block when appropriate. To stop TriagePilot writes, merge mode: shadow; events governed by that base record decisions without writes. Review the GitHub ruleset separately so a required check does not remain waiting for a shadow-mode result.

TriagePilot never edits your ruleset. The operator controls protected branches and required checks.

Run the shadow-mode quickstart →

Sources and next steps

TriagePilot is Fair Source/source-available under FSL-1.1-Apache-2.0. Internal self-hosting is permitted subject to the license; competing commercial use is restricted. Each version receives its Apache 2.0 future license after two years.

Explore TriagePilot or compare the GitHub reviewer-assignment options.