> For the complete documentation index, see [llms.txt](https://docs.codna.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codna.ai/guides/review.md).

# Codna Review

Codna Review reads a pull request when it opens (or on demand) and posts **high-confidence inline findings** — correctness, security, and performance bugs anchored to the changed lines. Reply `@codna fix` on any finding to open a verified, test-green fix PR for it.

The review pass is **read-only**. It doesn't run your code, expose secrets, apply patches, or hold a write token — it reuses the same repository graph as `codna fix` but emits structured findings instead of a patch. The verified fix is a separate path, invoked only when you ask for it.

{% hint style="info" %}
Bugbot tells you what might be wrong. Codna Review posts the finding **and**, on `@codna fix`, opens a test-green, risk-gated fix PR for it.
{% endhint %}

## What a finding looks like

Each finding is posted as one inline comment on the changed line, with a severity, a category, a plain-English explanation, and — where possible — a suggested patch you can commit from the GitHub UI:

> **🔴 HIGH · security** — Timing-attack vulnerability: naive `==` replaces a constant-time compare
>
> `verify_token` compares the token with `provided == expected`, which short-circuits on the first differing byte and leaks timing usable to recover the secret.
>
> *Reply `@codna fix` and Codna opens a verified, test-green, risk-gated fix PR.*

Codna posts **one review per push** and creates a **"Codna Review"** check. The check is **non-blocking by default** — findings never fail your build unless you opt in (`--blocking`).

## How it works

{% stepper %}
{% step %}

#### Scope the diff

Codna reviews only the changes on the PR (its diff). In the GitHub App, re-reviews are **incremental** — only the commits pushed since the last review — so they stay fast and quiet; pass `--full` to review the whole PR again. An explicit `--diff origin/main...HEAD` (as the GitHub Action passes) reviews that full range.
{% endstep %}

{% step %}

#### Understand, then review

The same deterministic engine that powers `codna fix` builds a graph around the changed files and hands the read-only review agent a tight evidence bundle. The sidecar disables writes and shell for the review agent, so the pass is read-only.
{% endstep %}

{% step %}

#### Post findings, once

Findings are resolved to GitHub diff anchors and posted as inline comments; anything that can't be anchored goes to the summary. A per-finding fingerprint dedups across pushes, so a force-push never respawns the same thread. Only findings at or above `--min-confidence` (default `0.75`) are posted, capped at `--max-findings` (default `10`).
{% endstep %}

{% step %}

#### Fix on request

Reply `@codna fix` to a finding and Codna routes it into the verified-fix workflow: it localizes, patches, runs the tests, clears the Monte-Carlo risk gate, and opens a fix PR stacked on the branch — or, if the patch fails to verify, replies fail-closed and pushes nothing.
{% endstep %}
{% endstepper %}

## Triggers

Codna Review runs from the CLI and the GitHub Action today. The hosted GitHub App uses the same review/fix code paths, but automatic PR review and comment-triggered fixes require the App to be subscribed to the Pull requests, Issue comments, and Pull request review comments events in the GitHub App settings. The App also needs Pull requests `write` and Checks `write` repository permissions so it can post review findings and status checks.

| Trigger                                                                  | Result                                                                              |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| CLI `codna review` or GitHub Action `mode: review`                       | Review the requested diff and post findings when configured with a token            |
| GitHub App PR `opened` / `synchronize` / `reopened` / `ready_for_review` | Automatic review of the new changes when the Pull requests event is enabled         |
| GitHub App `@codna review` on a PR                                       | Re-review on demand when Issue comments or Pull request review comments are enabled |
| GitHub App `@codna fix` reply to a Codna finding                         | Verified fix PR for that finding when Pull request review comments are enabled      |

`@codna review` is read-only. `@codna fix` spends a metered run and pushes a branch, so it is gated to commenters with write access and only acts on a comment the Codna App actually authored — the finding marker cannot be forged.

## From the CLI

Review the working changes locally, or a real PR:

```bash
# Review uncommitted changes against HEAD
codna review .

# Review a diff range
codna review . --diff origin/main...HEAD

# Review a PR and post the findings + the "Codna Review" check
codna review --pr owner/repo#123 --post
```

`--post` needs `--pr` and a write token (`--github-token`, or `$GITHUB_TOKEN` / `$CODNA_GITHUB_TOKEN`).

| Flag                | Default          | Purpose                                                                   |
| ------------------- | ---------------- | ------------------------------------------------------------------------- |
| `--pr`              | —                | PR to review/post to: `123`, `owner/repo#123`, or a PR URL                |
| `--post`            | off              | Post one review + the "Codna Review" check (needs `--pr` + a write token) |
| `--diff` / `--base` | `HEAD`           | Diff range / base ref to review                                           |
| `--min-confidence`  | `0.75`           | Only report findings at or above this confidence                          |
| `--max-findings`    | `10`             | Cap the number of findings                                                |
| `--effort`          | `medium`         | Review depth: `low` (cheaper) · `medium` · `high` (more thorough)         |
| `--full`            | off              | Review the whole PR, not only commits since the last review               |
| `--blocking`        | off              | Fail the check on a blocking-severity finding                             |
| `--model`           | provider default | Planner/review model, e.g. `openai/gpt-5`                                 |
| `--json`            | off              | Emit the review result as JSON                                            |

For the complete flag list (including the legacy engine-backed `--triage` mode), see the [CLI Reference](/reference/cli.md).

## From the GitHub Action

Set `mode: review` to review the triggering PR and post findings + the check. It is read-only and holds no `contents: write` token. On `pull_request` events the action fetches the base branch and reviews `origin/<base>...HEAD`. For non-PR events, pass `diff` explicitly, for example `diff: origin/main...HEAD`.

{% code title=".github/workflows/codna-review\.yml" %}

```yaml
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  checks: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: thyn-ai/codna-action@v1
        with:
          mode: review
          effort: medium          # low | medium | high
          # min-confidence: "0.75"
          # blocking: "false"      # non-blocking by default
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

{% endcode %}

## Noise control and review policy

* **Confidence + cap.** `--min-confidence` and `--max-findings` keep the review to the findings worth a human's attention.
* **Dedup.** A line-independent fingerprint means one finding is one thread, even across force-pushes.
* **Project rules.** Codna reads your repository's review guidance — `AGENTS.md`, `.codna/review.md`, or a Cursor `BUGBOT.md` (`.cursor/BUGBOT.md`) — and the `review:` block of `codna.yaml` from the PR's checked-out head, so guidance you add on a branch takes effect on that PR's review.

## Security

The review pass and the `@codna fix` follow-up are separate privilege tiers: review holds no write token, and only the gated fix step mints a scoped token to open a PR.

```mermaid
flowchart TD
    ev[PR opened / @codna review] --> rev[Review worker<br/>read-only · no write token · no shell]
    rev --> post[Post inline findings +<br/>non-blocking 'Codna Review' check]
    post --> reply{Reply @codna fix?<br/>needs write access +<br/>Codna-authored finding}
    reply -->|no| done([done])
    reply -->|yes| fix[Verified-fix path<br/>localize → patch → tests → risk gate]
    fix -->|pass| pr[Mint scoped token →<br/>open fix PR]
    fix -->|fail| closed[Reply fail-closed ·<br/>push nothing]
```

The review worker treats every PR — especially a forked one — as untrusted input:

* Read-only is enforced below the model: no writable filesystem, no shell or code execution, no network egress beyond the approved Codna and GitHub calls, and **no GitHub write token** in the review worker.
* The verified-fix follow-up keeps the same privilege separation as `codna secure`: analysis runs without write access; only the controlled fix step mints a scoped token to open a PR.

## Next steps

* [CLI Reference](/reference/cli.md) — every `codna review` flag.
* [Security Autofix](/guides/security-autofix.md) — the reachability-proving, attested security path.
* [GitHub Action](/guides/github-action.md) — `fix`, `review`, and `secure` modes in CI.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.codna.ai/guides/review.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.