> 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/github-app.md). # GitHub App Install the Codna GitHub App. It reviews every pull request, answers @codna review and @codna fix, fixes red CI on a PR, proves scanner findings, and reports on merge-queue commits. The Codna GitHub App is the hosted way to run Codna on a repository. It reviews pull requests when they open or change, answers `@codna review` and `@codna fix`, opens fix pull requests from issue labels and red CI, proves scanner findings, and posts every result back as the `codna-ai` bot. {% hint style="info" %} The App runs the same `codna` commands you run on your machine: `codna review`, `codna fix`, `codna secure`. What it posts reads the same as `codna review --post` from the CLI or `mode: review` in the [GitHub Action](/guides/github-action.md). {% endhint %} ## App vs. Action | | GitHub App | GitHub Action | | -------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------- | | Runs | Hosted by Codna | Your CI runner | | Setup | Install the App once | Add a workflow step | | Keys | Keyless. Metered against your linked Codna account, or your own model key added on the account page | A model provider key in your job environment | | Triggers | Pull requests, comments, labels, red CI, code-scanning alerts, merge queue | Whatever your workflow triggers on | | Best for | Automatic review and fixes on every pull request | Gating you control in your own pipeline | You can use both. For the CI path, see [GitHub Action](/guides/github-action.md). ## Install Install the Codna GitHub App on your account or organization and grant it the repositories you want covered. Codna reviews the next pull request that opens. Link the installation to your Codna account to enable fixes. Each account includes a managed-model allowance of about $5 a month; add your own model key on the account page for uncapped, self-billed usage. Until an installation is linked the App spends nothing: the check reports `codna: account not linked` and a comment says how to link it. The CLI never needs this. An admin can turn automatic fixes off for an organization from the account page (Security → Codna automation). Reviews keep running. ### Permissions The App requests per-job permissions, each scoped to the repository the event came from and issued as a short-lived token: | Job | Permissions | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | review | `contents: read`, `pull_requests: write`, `checks: write`, `statuses: read`. It never pushes. *Commit statuses: read* lets the review name a failed commit status, such as a deployment, next to its verdict. | | fix | `contents: write`, `pull_requests: write`, `checks: write`, `issues: write`, `workflows: write`. | | secure | `contents: read`, `security_events: read`, `checks: write`, `issues: write`. | | CI-failure triage | `actions: read` and `checks: read` to read the failed job's steps and log, or `actions: write` and `checks: read` to also re-run it. Optional: without it the fix runs without CI evidence and its check summary asks for the permission. | | merge queue | `pull_requests: read`, `checks: write`. | Why `workflows: write` for fix: GitHub refuses any push by an App to a branch whose `.github/workflows` files differ from the default branch unless the App holds it. If an installation declined it, a `@codna fix` on such a branch replies with the exact remedy and spends nothing. ## Triggers | Trigger | What Codna does | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | A pull request is opened, synchronized, reopened, or marked ready for review | Reviews the change and posts a `codna review` check. Drafts are skipped. | | `@codna review` at the start of a line, in a PR comment or a review thread | Runs a review. Anyone who can comment can ask. | | `@codna fix` as a **reply** to a Codna review finding | Opens a fix pull request for that finding, stacked on the PR branch. The commenter needs write access. | | The label `codna-fix` on an issue | Opens a fix pull request for the issue. | | The label `codna-secure` on an issue | Runs a read-only security pass. | | A code-scanning alert is created, reopened, or appears in a branch | Runs `codna secure` on the alert. | | A check suite fails on a pull request | Triages the failure, then opens a fix on the PR branch when it is a code defect. | | A merge queue requests checks | Posts `codna review` on the group commit with the PR head's verdict. | The only comment verbs are `review` and `fix`. They are matched at the start of a line, case-insensitively. Every trigger is tied to a human action on a pull request or issue. A red default branch never triggers anything. ## What you see on the pull request ### The check One Check Run per job, named exactly like the CLI command: `codna review`, `codna fix`, `codna secure`. The `codna review` check appears as **Queued** the moment your push is accepted, with the summary `codna review queued (pull_request_synchronize); waiting for a worker`. It flips to **In progress** when the review starts, and completes with the verdict. | Conclusion | When | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `success` | No findings. | | `neutral` | Findings were posted and blocking is off (the default). | | `failure` | Blocking is on (`review.blocking.enabled: true` in `codna.yaml`) and a finding hit a blocking severity, or the review ran out of time (`review_timeout`). | If you push again while a review is still waiting or running, the old head's check completes `neutral` with `superseded by -- this commit is no longer the pull request head; see the check on the current head.` The new head gets exactly one check of its own. ### The review Codna posts one review per push. Each finding is an inline comment on the changed line with a severity (`HIGH`, `MEDIUM`, `LOW`), a category (`correctness`, `security`, `performance`), an explanation, and, where possible, a suggestion you can commit from the GitHub UI. Findings that cannot be anchored to a line go in the review body. A clean review reads `**codna review** — no high-confidence issues found. ✅` The review is posted as an **Approve** when no medium or high finding is in this pass and no earlier Codna medium/high thread on the pull request is still unresolved. Otherwise it is posted as a comment. Codna never requests changes. The check summary carries one of these lines: | Line | Meaning | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | `✅ Approved: no medium/high findings and no unresolved codna threads.` | The approval counts toward a branch rule that requires approving reviews. | | `⏸ Not approved: 2 medium/high finding(s) in this review; 1 earlier codna finding thread(s) at medium/high still unresolved -- resolve them once addressed.` | Resolve the threads once the findings are addressed. The next push approves. | | `⏸ Not approved: the pull request head moved from 9f3c1a2b to 4e7d8c01 while this review ran; the current head gets a review of its own.` | You pushed during the review. | | ``Approval is turned off for this repository (`review.approve: false`).`` | You turned approvals off in `codna.yaml`. | The App cannot approve a pull request it authored itself, so its own fix PRs get a comment that says so. An approval is about the diff, not a merge go-ahead. When a required check is red on the head at the time the review posts, the verdict line is followed by one more: > 🔴 Heads-up: head 9f3c1a2b is red -- required check(s) failing at review time: `CI` (failure). This review's verdict is about the diff, not a merge go-ahead. For what a finding looks like, the noise controls, and the `review:` block of `codna.yaml`, see [codna review](/guides/review.md). ### Comment commands | You write | Codna does | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@codna review` | Reviews the pull request again. By default only the commits since Codna's last review are reviewed. | | `@codna fix` as a reply to a Codna finding | Replies `🔧 On it — analyzing this finding and opening a verified fix PR if the patch passes tests and clears the risk gate.`, then opens a fix pull request stacked on the PR branch, or replies that it could not and pushed nothing. | Replies you may see to `@codna fix`: | Reply | Meaning | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `✅ Opened a verified fix PR: ` | The fix pull request is open. | | `✅ Already opened a verified fix PR: ` | The same finding was fixed before. Codna reuses the pull request. | | `⚠️ Codna couldn't open a verified fix for this finding — the patch didn't clear the test + risk gate, so nothing was pushed (fail-closed). You can apply the fix manually.` | No branch was pushed. | | `⚠️ Codna couldn't complete this fix — . Nothing was pushed.` | The run failed before a patch. | | `⚠️ @codna fix is limited to people with write access to this repository.` | Write access is checked against the repository's collaborator permission. | | `@codna fix only works as a reply to a codna review finding.` | Reply on the finding's thread. | | `@codna fix can't auto-fix a forked-PR finding yet (Codna can't push to the fork's branch). Apply the suggested change manually for now.` | Fork pull requests get the suggested change instead. | A `@codna fix` reply never goes silent. If the job fails before it can post anything, Codna still replies in the thread with the error code. ## Fixes Every fix Codna opens is a pull request. It carries a body with the issue, the root cause, the symbols touched, and a confidence score, and ends with `_Review before merging._` The branch is named `codna/`. Codna never merges. Fix commits are authored as `codna-ai[bot] <293953567+codna-ai[bot]@users.noreply.github.com>`, a real GitHub identity. If your repository runs a CLA bot, add `codna-ai[bot]` to its allowlist the way you would `dependabot[bot]`. ### From a finding `@codna fix` on a Codna finding runs `codna fix` with that finding as the issue, at the PR head, and opens the fix against the pull request's own branch, so it stacks on the change under review. The same finding never opens two pull requests. ### From a label The label `codna-fix` on an issue runs `codna fix` with the issue's title and body as the issue text. Codna comments on the issue when it is done: * `✅ Codna opened a fix for this issue: ` * `⚠️ Codna couldn't finish this fix: ` ### From red CI on a pull request When a check suite fails on a pull request, Codna triages before it spends anything: 1. If the PR head has moved on, or the suite was re-run green, the `codna fix` check ends `neutral`. 2. If the failing step is infrastructure (a download, an install, a registry or network error, a runner that died, a full disk), the check ends `neutral` with `**codna fix** — not a code defect; nothing was spent.`, and with `actions: write` Codna re-runs the failed jobs once. A second failure of the same kind is left for you. 3. Otherwise the failing step and the log around its error become the issue, and Codna runs the repository's tests in a sandbox to find what is failing, fixes it, and opens the pull request on the PR branch. Codna's own check suite never triggers a fix. Only one CI-failure fix is attempted per pull request head per 24 hours. ### Test command per repository A CI-failure fix and `codna fix --tests` run the repository's tests inside Codna's sandbox to find what is failing. By default that is `pytest`; when the repository declares its own runner, Codna uses that instead: | Source | Command Codna runs | When | | ------------------------------------------------------------------------- | ------------------ | ------------------------------------------- | | `fix.test_command` in the repository's `codna.yaml` | as written | always wins | | a `test` task in `pixi.toml` (or `[tool.pixi.tasks]` in `pyproject.toml`) | `pixi run test` | the repository is pixi-managed | | `uv.lock` that locks pytest, next to pytest config | `uv run pytest` | the repository is uv-managed | | otherwise | `pytest` | pytest config at the root or one level down | ```yaml # codna.yaml, committed in the repository fix: test_command: pixi run test ``` The command runs from the repository root with the network denied and credentials scrubbed. Any pytest it reaches writes the JUnit report Codna reads for per-test ids, so a task that wraps pytest needs no changes. On the command line the same precedence applies to `codna fix --tests`, with `--test-cmd` first. Hosted test runs ship `pytest` and no other toolchain. When the sandbox cannot run the tests (the runner is not installed, pytest cannot import the test modules, or no runner is detectable), the `codna fix` check ends `neutral`: `**codna fix** — skipped: Codna could not run this repository's tests in its sandbox: … No fix was attempted.` That is a property of the environment, not of the pull request, so nothing is marked failed and nothing is retried. For such repositories, hand Codna CI's own report with `codna fix --from-junit` from the [GitHub Action](/guides/github-action.md) or the CLI. ## Secure The label `codna-secure` on an issue, or a code-scanning alert that is created, reopened, or appears in a branch, runs `codna secure` on the repository. This pass is read-only: it classifies reachability and never opens a pull request. On an issue it comments `✅ Codna finished the secure pass for this issue.` See [Security Autofix](/guides/security-autofix.md) for the verdicts. ## Merge queues A repository that gates `main` with a merge queue asks every required check to report on the queue's temporary group commit. When the queue requests checks, Codna posts `codna review` on the group commit with the verdict of the queued pull request's head: > codna review: inherited from PR #482 at 9f3c1a2b (success). Merge groups are not re-reviewed; the queued PR head is what was reviewed. If the PR head carries no completed review, the group check fails with `codna review: no completed review found on PR #482's head 9f3c1a2b. Comment @codna review on the PR, then re-queue it.` Nothing changes for repositories without a queue. ## Limits | Limit | Behaviour | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Review window | A review gets 4 minutes for a small pull request and up to 20 minutes for a large one, sized by lines, files and prompt size. Out of time, the check fails with `review_timeout` and says to comment `@codna review` (the retry gets a longer window) or to split the pull request. | | Job window | A job ends after 30 minutes. The check completes `neutral` saying it passed its deadline. | | Order | Reviews are always started before fixes. | | CI-failure fixes | One per pull request head per 24 hours. | | `@codna fix` | Only as a reply to a Codna finding, only from people with write access, not on fork pull requests. | | Hosted test runs | `pytest` only. Other toolchains end the `codna fix` check `neutral`. | | Findings | At most 10 per review at a confidence of 0.75 or higher, unless `codna.yaml` says otherwise. | | Interrupted jobs | A job interrupted by a restart is run once more; its old check is closed, never left spinning. | ## The public feedback repo Reports filed with `codna report` land in [thyn-ai/feedback](https://github.com/thyn-ai/feedback). When a maintainer labels a report there `codna-fix`, Codna routes the fix to the product repository named by the report's `product:` label and comments the outcome on the report. ## Next steps * [codna review](/guides/review.md) — what a finding looks like, the noise controls, and the `review:` block. * [Security Autofix](/guides/security-autofix.md) — the reachability verdicts behind `codna secure`. * [Models & BYOK](/concepts/models-and-byok.md) — the managed allowance vs. your own key. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.codna.ai/guides/github-app.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.