-
Notifications
You must be signed in to change notification settings - Fork 2k
PR Agent
The .NET MAUI PR Agent runs an automated review that combines code analysis, regression evidence, test verification, alternative-fix exploration, and deep UI tests when applicable.
Note
This page describes the deployed /review workflow first. Local
Review-PR.ps1 runs and direct use of the pr-review skill are separate
paths and are not identical to production.
For the canonical operator guide, see
.github/docs/pr-review-workflow.md.
Production behavior follows the executable workflows and scripts when prose
documentation differs.
Last verified on 2026-07-31 against
dotnet/maui@fc1536c.
| Command | Purpose |
|---|---|
/review |
Run the full automated PR review. |
/review android |
Run the full review using the Android platform path. |
/review ios |
Run the full review using the iOS platform path. |
/review catalyst |
Run the full review using the Mac Catalyst platform path. |
/review windows |
Run the full review using the Windows platform path. |
/review tests |
Analyze current CI/test failures without running the full PR review. |
The commands require write, maintain, or admin repository permission.
Community contributors can ask a maintainer to run the appropriate command.
/review accepts an optional platform and an optional pipeline branch. Both a
positional platform and explicit flags are supported:
| Option | Forms | Purpose |
|---|---|---|
| Platform |
/review <platform>, -p <platform>, --platform <platform>, -p=<platform>, or --platform=<platform>
|
Selects the review platform: android, ios, catalyst, or windows. When omitted, the platform is inferred from platform/* labels, defaulting to android. |
| Pipeline branch |
-b <branch>, --branch <branch>, -b=<branch>, or --branch=<branch>
|
Runs the pipeline scripts from <branch> instead of the default main. Used to exercise in-development reviewer changes. Malformed refs (path traversal, empty) fall back to main. |
The options can be combined in any order, for example:
/review windows
/review -p ios
/review -b my-reviewer-branch -p windows
/review tests is a separate workflow. It classifies current test failures and
posts a Test Failure Review; it does not approve, request changes, apply review
labels, trigger a full review, or change the PR.
There is no /review rerun command. Run /review again when an immediate fresh
review is needed.
flowchart LR
A[Maintainer comments /review] --> B[GitHub validates command and applies review lock]
B --> C[Azure DevOps: ReviewPR]
C --> D{Relevant UI test categories?}
D -->|Yes| E[RunDeepUITests]
D -->|No| F[Update AI Summary review]
E --> F
F --> G[Cleanup review lock]
The public entry point is
review-trigger.yml.
It:
- verifies that the comment is on an open pull request;
- checks the commenter's repository permission;
- parses the platform and optional pipeline branch;
- infers a platform from
platform/*labels when none was supplied; - applies
s/agent-review-in-progressas a review lock; - queues the
maui-copilotpipeline; - minimizes the authorized command comment as resolved.
If s/agent-review-in-progress is already present, another /review command
does not start a second review. The pipeline clears the lock in a cleanup stage
that runs even when earlier stages fail.
When no platform is supplied, the trigger maps PR labels as follows:
| PR label | Review platform |
|---|---|
platform/iOS |
ios |
platform/macOS or platform/maccatalyst
|
catalyst |
platform/android |
android |
platform/windows |
windows |
If the labels are inconclusive, the workflow defaults to Android. Use an explicit platform argument when that default is not appropriate.
The Azure DevOps pipeline has these contributor-facing stages:
- ReviewPR prepares the PR, detects relevant UI categories, cross-references regressions, runs the gate, generates and compares candidates, performs expert evaluation, applies PR-finalization recommendations when warranted, and publishes review artifacts.
- RunDeepUITests runs detected UI test categories on the selected platform when relevant categories were found.
- UpdateAISummaryComment submits or updates the final AI Summary review using the review and deep-test evidence.
-
CleanupReviewLock removes
s/agent-review-in-progress.
The analysis step does not hold the GitHub write credential used for comments, reviews, labels, or PR metadata. Trusted posting steps apply those changes after processing the generated artifacts.
The gate checks whether tests in the PR demonstrate the reported bug by failing without the proposed fix and passing with it.
| Result | Meaning |
|---|---|
PASSED |
Tests fail without the fix and pass with it. |
SKIPPED |
No applicable tests were detected. |
INCONCLUSIVE |
Build or environment failures prevented verification. |
FAILED |
The tests did not behave as expected. |
Only a genuine FAILED gate result signals a blocking validation failure.
SKIPPED and INCONCLUSIVE remain visible evidence but are not treated as
proof that the PR's fix is wrong. The gate result appears in the AI Summary
review; do not expect a separate gate comment.
Not every fix can be verified. A skipped or inconclusive gate, unavailable test runner, or environment failure must be interpreted as missing evidence rather than a passing test result.
Production does not use a fixed four-model roster. The configured Copilot model runs sequential orchestration steps that:
- gather issue and PR context and explore a capped set of meaningfully
different
try-fixalternatives; - run expert evaluation of the PR's fix;
- compare the original PR, a PR candidate hardened with expert feedback, and viable alternatives;
- record the selected winner and final recommendation.
Candidates can use issue context, code-review findings, regression evidence, test results, and lessons from earlier failed attempts. "Independent" means exploring a different approach rather than ignoring useful review evidence.
If the PR-based candidate wins, applicable expert findings may be posted as a
separate inline COMMENT review. If an alternative wins, its unified diff is
included in the AI Summary's future-action guidance. Alternative candidate code
is never pushed to the contributor's branch.
| Surface | Behavior |
|---|---|
| GitHub review | Submits APPROVE, REQUEST_CHANGES, or COMMENT. Trusted gate and deep-test evidence can veto or soften the generated recommendation. |
| Inline findings | May submit a separate COMMENT review with findings on changed lines when the winner remains PR-based. |
| Labels | Applies review outcome, gate, candidate, queue, and lock labels where supported. |
| PR title and description | May apply a pr-finalize recommendation when the existing metadata is stale, inaccurate, vague, or incomplete. |
| Command comment | Minimizes an authorized /review command as resolved while preserving its history. |
| Alternative fix | Publishes the winning alternative as review guidance and a diff; it does not push it. |
| Merge state | Does not merge the PR. Human maintainers retain merge authority. |
The textual recommendation and outcome labels are generated from agent artifacts. The final formal review event is additionally checked against trusted gate and deep-test results, so the labels and the final review event can differ.
The pipeline publishes a CopilotLogs artifact containing the review evidence.
Depending on the PR and available test signal, the AI Summary review can include:
- gate status;
- detected and deep UI test results;
- regression cross-reference;
- Pre-Flight context;
- code-review findings when produced;
- candidate and alternative-fix comparison;
- the selected winner;
- recommended PR title and description changes;
- the final recommendation and future actions.
Treat the review as assistant-generated evidence. An automated APPROVE does
not merge the PR, and an automated REQUEST_CHANGES can be reassessed or
overridden by a human reviewer.
A maintainer can run /review again for an immediate fresh review. The
repository also contains an hourly
rerun-review-scanner
that processes PRs already carrying s/agent-ready-for-rerun.
Current public source defines deterministic eligibility for new PR-author
commits or non-command comments, but does not show an active caller applying the
queue label. Until that producer is wired publicly, do not rely on author
activity alone to queue a rerun; ask a maintainer to run /review.
Maintainers developing or diagnosing the workflow can invoke the orchestration script directly:
pwsh .github/scripts/Review-PR.ps1 -PRNumber 33687
pwsh .github/scripts/Review-PR.ps1 -PRNumber 33687 -Platform iosThe local script allows its Copilot model to be overridden with
COPILOT_REVIEW_MODEL. Exact model names and defaults are intentionally not
documented here because they change independently of the workflow contract.
The direct
pr-review skill
has its own contract and currently differs from production orchestration.
In particular, the production prompt describes Pre-Flight as context gathering,
while the direct skill's
pr-preflight.md
also requires deep code review. Production performs explicit expert evaluation
later in the review even when the earlier code-review artifact is absent.
Both the deployed workflow and the local script are GitHub-specific.
Review-PR.ps1 requires a -PRNumber, uses the gh CLI, and fetches
pull/<number>/head. Review output is spread across per-phase Markdown, JSON
artifacts such as winner.json and inline-findings.json, plain-text verdict
files, and trusted Azure DevOps output variables. GitHub-specific posting
scripts consume those outputs and publish reviews directly to dotnet/maui.
Although winner.json has its own schema version, the current public
implementation does not define a single versioned, source-neutral review
contract or support a non-GitHub review surface. Treat the combined artifact
names and layout as implementation details that can change without notice.
This is a representative list, not the canonical label inventory:
| Label | Meaning |
|---|---|
s/agent-review-in-progress |
A review is currently running; another /review will not start. |
s/agent-reviewed |
The automated review workflow completed far enough to record a review. |
s/agent-approved |
The generated report recommends approval. |
s/agent-changes-requested |
The generated report recommends changes. |
s/agent-gate-passed |
Tests verified the expected fail-without-fix/pass-with-fix behavior. |
s/agent-gate-failed |
The gate produced a genuine failed result. |
s/agent-fix-win |
An alternative candidate was selected over the PR's fix. |
s/agent-fix-pr-picked |
The PR-based candidate was selected. |
s/agent-ready-for-rerun |
Queue marker consumed by the hourly rerun scanner. |
Gate labels currently have two implementation paths.
Review-PR.ps1
directly attempts to apply s/agent-gate-skipped for SKIPPED and
INCONCLUSIVE, but that label is not present in the live repository label set,
so the attempt fails. The shared
Update-AgentLabels.ps1
helper maps only PASSED to s/agent-gate-passed and FAILED to
s/agent-gate-failed; skipped, inconclusive, or empty results produce no gate
signal label there. Until the two paths and repository labels are reconciled,
do not treat the absence of a gate label as a specific verdict; use the gate
result in the AI Summary instead.
For current definitions, see
Update-AgentLabels.ps1
and the repository's
agent labels.
Alternative candidates reduce anchoring on the implementation already present in the PR. They are informed by concrete evidence, then compared against the PR and expert-hardened candidates. This helps the review explain whether the submitted change is the strongest available approach without pretending that candidate generation occurs "in a bubble."