> ## 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.
7. Qodex reviews the diff and creates candidate findings.
8. Findings are filtered by confidence, severity threshold, and excluded paths.
9. Findings inside the diff become inline comments.
10. Findings outside the diff appear in the walkthrough.
11. Verification probes may run against an allowed preview host.
12. Qodex posts the walkthrough, inline comments, and Check Run conclusion.

## Events that trigger review

Qodex reviews:

* `opened`
* `synchronize`
* `reopened`
* `@qodex review` slash commands

Other GitHub PR actions are acknowledged and skipped.

## Settings that matter most

| Setting                         | What it controls                     |
| ------------------------------- | ------------------------------------ |
| `pr_review.enabled`             | Whether Qodex reviews the repo.      |
| `pr_review.severity_threshold`  | Which findings appear.               |
| `pr_review.paths.exclude`       | Which changed files are ignored.     |
| `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

<CardGroup cols={2}>
  <Card title="How a review fires" icon="webhook" href="/pr-review-how-it-fires">
    See the full PR review lifecycle.
  </Card>

  <Card title="Inline findings" icon="message-square" href="/pr-review-inline-findings">
    Learn how comments are placed.
  </Card>

  <Card title="Check Run and merge gating" icon="shield-check" href="/pr-review-check-run">
    Configure merge protection.
  </Card>

  <Card title=".qodex.yaml reference" icon="file-code" href="/qodex-yaml-reference">
    Control review behavior per repo.
  </Card>
</CardGroup>