ADO Pilot posts a single PR status check on every reviewed pull request. You can require it as a branch policy to gate PR completion on the AI [verdict](glossary.md#verdict). This page documents the check's identifier, every state it can take, and how to wire it up in Azure DevOps. ## Identifier The status check uses a fixed two-part context. Type both fields exactly as shown — the search box in branch policies is case-sensitive. | Field | Value | | ------- | -------------- | | `genre` | `adopilot` | | `name` | `ai-pr-review` | The combined display label in the Azure DevOps UI is `adopilot/ai-pr-review`. ## States ADO Pilot writes one of four states to every PR it observes. The state always reflects the latest [iteration](glossary.md#iteration) — a new push to the source branch resets the check to `pending`. | State | Meaning | Description text shown in ADO | | ----------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `pending` | Review queued or in progress. | "AI review queued" or "AI review in progress" | | `succeeded` | Review complete with a `PASS` or `ADVISORY` [verdict](glossary.md#verdict), or skipped with no review. | "AI review complete - X blockers, Y warnings, Z suggestions" (completed, zero-count categories omitted) / "AI review skipped — no reviewable changes" or "AI review skipped — all files excluded by configuration" (skip path) | | `failed` | Review complete with a `FAIL` verdict (one or more [blockers](glossary.md#blocker)), or quota exhausted. | "AI review complete - X blockers, Y warnings, Z suggestions" (verdict) / "AI review blocked — review credit quota exhausted. Upgrade your plan or wait for the next billing period." (quota) | | `error` | Review encountered an unrecoverable error and could not complete. | "AI review failed to complete" | ### State transitions ```text pending ──► in-progress ──► succeeded ├─► failed └─► error (skip path: succeeded posted directly — ADO Pilot never posts pending or in-progress) (quota exhausted: failed posted directly — ADO Pilot never posts pending or in-progress) ``` Empty-diff or fully-excluded PRs are detected before review starts and post `succeeded` directly with a skip description — no `in-progress` step. ## Wiring as a required branch policy Any user with **Edit policies** on the target branch can make the check a hard or soft gate. 1. In Azure DevOps, open **Project settings → Repos → Repositories**, pick the repository, then open the **Policies** tab. 2. Under **Branch Policies**, select the branch (for example `main`). 3. Scroll to **Status Checks** and click **+** (add status check). 4. In the **Status to check** picker, search for `adopilot/ai-pr-review` and select it. 5. Choose how strict you want the gate to be: - **Required** — the PR cannot complete until the check is `succeeded`. `pending` blocks completion; `failed` or `error` blocks until either a new push triggers a fresh review or an admin overrides the policy. - **Optional** — the check is visible on the PR but does not block completion. 6. Click **Save**. {% callout type="info" title="Soft-gate behavior" %} A non-required (optional) check shows the same states and descriptions but lets PR authors complete merges regardless of verdict. It is the recommended starting point for teams trialing ADO Pilot. {% /callout %} ## Behavior under a required policy | Posted state | Effect on PR completion | | ------------ | --------------------------------------------------------------------------------- | | `pending` | Blocked — branch policy waits for a terminal state. | | `succeeded` | Satisfied — PR can complete (subject to other policies). | | `failed` | Blocked — push a fix to re-run the review, or have an admin override. | | `error` | Blocked — push a new commit to trigger a fresh review, or have an admin override. | {% callout type="warning" title="There is no manual override of the verdict" %} The verdict is determined by the AI review. The only ways to clear a `failed` or `error` state are to push a new commit (which triggers a fresh review on the new [iteration](glossary.md#iteration)) or to have a project administrator bypass the branch policy. {% /callout %} ## Description text ADO Pilot writes a description to every status post; you can read it on the PR Overview page next to the check name. | When | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------------- | | Initial post | "AI review queued" | | Active | "AI review in progress" | | Complete (PASS/ADVISORY/FAIL) | "AI review complete - X blockers, Y warnings, Z suggestions" (zero-count categories are omitted) | | Quota exhausted | "AI review blocked — review credit quota exhausted. Upgrade your plan or wait for the next billing period." | | Error | "AI review failed to complete" | | Skipped (empty diff) | "AI review skipped — no reviewable changes" | | Skipped (all excluded) | "AI review skipped — all files excluded by configuration" | ### Description format for completed reviews The description uses a hyphen `-` as separator and omits categories with zero findings. For example: - A review with 2 blockers and 1 warning but no suggestions: `"AI review complete - 2 blockers, 1 warning"` - A review with only 1 suggestion: `"AI review complete - 1 suggestion"` - A review with no findings at all (PASS): `"AI review complete"` ## Troubleshooting - **Check stays on `pending` for more than 15 minutes.** Most reviews complete in 2–5 minutes, and a few legitimately take 10 minutes or more; delays beyond that usually indicate a system-side processing delay. See [Stuck review](../troubleshooting/stuck-review.md). - **Old verdict still showing after a push.** Azure DevOps caches the previous status until the new iteration's review finishes. Refresh the PR Overview after 1–2 minutes. - **The check doesn't appear in the branch policy picker.** Confirm you typed the context exactly as `adopilot/ai-pr-review`. The picker only lists statuses that have been posted at least once on a PR in that repository — open and close a test PR first if necessary. - **Reviews aren't running because you've exhausted your plan.** When your tenant has no review credits available, ADO Pilot posts a `failed` status check with the quota-exhausted message above. See [Quota exceeded](../troubleshooting/quota-exceeded.md).