> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How does Qodex decide to review a PR?

> Qodex reviews a pull request only after webhook, repo-linking, config, filter, and optional verification checks pass.

# How does Qodex decide to review a PR?

Qodex reviews a PR only after it decides the GitHub event is actionable and the repository is linked to a Qodex project.

Then it reads repo config, reviews the diff, filters findings, optionally verifies them, and posts the result back to GitHub.

## Review decision flow

1. GitHub sends a `pull_request` event to Qodex.
2. Qodex verifies the webhook signature.
3. Qodex checks whether the action should trigger review.
4. Qodex finds projects linked to the repository.
5. Draft PRs are skipped until ready for review.
6. Qodex reads `.qodex.yaml` from the PR head SHA. If automatic reviews are off for the repo, only a review someone asked for continues.
7. Qodex checks the project's plan limits for the month and for this PR.
8. Qodex reviews the diff and creates candidate findings.
9. Findings are filtered by confidence, severity threshold, and excluded paths.
10. Findings inside the diff become inline comments.
11. Findings outside the diff appear in the walkthrough.
12. Verification probes may run against an allowed preview host.
13. Qodex posts the walkthrough, inline comments, and Check Run conclusion.

## Events that trigger review

Qodex reviews automatically on:

* `opened`
* `synchronize`
* `reopened`
* `ready_for_review`
* `edited`, when the PR's base branch changed

It also reviews when someone asks:

* `@qodex-ai review` slash commands
* The **Run review** button on the PR review page in Qodex

Requested reviews run even when automatic reviews are off for the repo. Other GitHub PR actions are acknowledged and skipped.

## Settings that matter most

| Setting | What it controls |
| - | - |
| `pr_review.enabled` | Whether opening or pushing to a PR starts a review automatically. Requested reviews run either way. |
| `pr_review.severity_threshold` | Which findings appear. |
| `pr_review.style_placement_threshold` | When style and maintainability notes are collected in the walkthrough instead of posted inline. |
| `pr_review.paths.exclude` | Which changed files are ignored. |
| `pr_review.authors` / `pr_review.base_branches` | Which authors and target branches Qodex reviews. |
| `pr_review.block_pr_merge` | Whether the Check Run can fail. |
| `pr_review.block_on_severity` | Which verified severity blocks. |
| `probes.preview_host_allowlist` | Which preview hosts Qodex may probe. |

## Check Run behavior

By default, Qodex is advisory.

If merge blocking is enabled and branch protection requires the Qodex Check Run, verified findings at or above the configured severity can block a merge.

## Next steps

> [card] [How a review fires](https://qodex.ai/docs/pr-review-how-it-fires.md)
>
> See the full PR review lifecycle.

> [card] [Inline findings](https://qodex.ai/docs/pr-review-inline-findings.md)
>
> Learn how comments are placed.

> [card] [Check Run and merge gating](https://qodex.ai/docs/pr-review-check-run.md)
>
> Configure merge protection.

> [card] [.qodex.yaml reference](https://qodex.ai/docs/qodex-yaml-reference.md)
>
> Control review behavior per repo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.