> 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

The Codna GitHub App is a hosted webhook that reacts to repository activity: it reviews pull requests, opens verified fix PRs, and proves scanner findings, posting results back as a GitHub App bot.

{% hint style="info" %}
The App runs local Codna. For each event it invokes the ordinary `codna` CLI (`review`, `fix`, `secure`) with the bundled local runtime. There's no separate hosted engine, and the worker never points Codna at a remote engine URL.
{% endhint %}

## App vs. Action

|          | GitHub App                    | GitHub Action               |
| -------- | ----------------------------- | --------------------------- |
| Runs     | Hosted (Codna's webhook)      | Your CI runner              |
| Setup    | Install the App once          | Add a workflow step         |
| Auth     | Keyless, metered per org      | Your `CODNA_API_KEY`        |
| Best for | Automatic PR review + fix bot | Pipeline gating you control |

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 then reviews new pull requests automatically.

The App requests least-privilege, per-job permissions, each scoped to the repository the event came from:

| Job    | Permissions                                                                 |
| ------ | --------------------------------------------------------------------------- |
| review | `contents: read`, `pull_requests: write`, `checks: write` (never pushes)    |
| fix    | `contents: write`, `pull_requests: write`, `checks: write`, `issues: write` |
| secure | `contents: read`, `security_events: read`, `checks: write`, `issues: write` |

## Triggers

| Trigger                                                       | Result                                                           |
| ------------------------------------------------------------- | ---------------------------------------------------------------- |
| PR opened, synchronized, reopened, or marked ready for review | Review the change, post a `Codna Review` check (drafts skipped). |
| `@codna review` on a PR or review thread                      | Run a review.                                                    |
| `@codna fix` reply on a review-comment thread                 | Open a verified fix PR (members/owners/collaborators only).      |
| A CI check suite fails                                        | Attempt a fix.                                                   |
| Label `codna-fix` on an issue                                 | Attempt a fix.                                                   |
| Label `codna-secure` on an issue                              | Run a security-reachability pass.                                |
| A code-scanning alert appears                                 | Run `secure` on the alert.                                       |

The only comment verbs are `review` and `fix`, matched at the start of a line and case-insensitively.

## Output

* A check run named after the job (`codna review`, `codna fix`, `codna secure`).
* A PR review with inline findings, plus a non-blocking `Codna Review` check.
* A fix PR for `@codna fix`, CI-failure, and label triggers, with an idempotency marker so the same fix opens once.
* In-thread replies acknowledging `@codna fix` and linking the PR.

Posts use a short-lived, repo-scoped installation token, so they appear as the App's bot account.

## Metering

The App is keyless and fail-closed. It injects only the linked org's Codna run credential:

* Each account includes a managed-model allowance for verified fixes.
* If an installation isn't linked to a Codna account, the App doesn't spend — it asks you to link the install or add your own model key for uncapped, self-billed usage.

## Next steps

* [Codna Review](/guides/review.md) — what the review bot reports and how to tune it.
* [Security Autofix](/guides/security-autofix.md) — the reachability + remediation flow.
* [Models & BYOK](/concepts/models-and-byok.md) — 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 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/github-app.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.