GitHub App
The recommended integration for GitHub-hosted repositories.
Kontrua uses a GitHub App rather than a personal access token. This means the integration is tied to your organisation (not a personal account), permissions are scoped precisely, and tokens rotate automatically.
Installation
Install the app
Go to Dashboard - Settings - Integrations and click Install GitHub App. You will be redirected to GitHub to select which repositories to grant access to. You can grant access to all repositories in an organisation or pick specific ones.Repository sync
After installation, Kontrua immediately syncs all accessible repositories. They appear under your dashboard within seconds.Configure each repo
Open a repository in the dashboard and set the watch branch. AGENTS.md and conventions are enabled by default (the codemap is opt-in); adjust them and the human documents as needed. The verdict starts immediately, on connect; corrections start on the next approval.
Permissions requested
| Permission | Level | Why |
|---|---|---|
| Contents | Read/Write | Read source files and existing context; commit the context branch that a PR is opened from |
| Pull requests | Read/Write | Open context PRs and post progress comments |
| Issues | Write | Post and update the run comment (GitHub serves PR comments through the issues API) |
| Statuses | Write | Publish the context verification result on the commit, so it can be required by branch protection |
| Metadata | Read | List repositories and branches |
Write access to contents is what lets Kontrua commit a branch and open a pull request from it. It is constrained by design, and the constraints are enforced in code, not by policy:
- Writes only ever land on a Kontrua-owned branch, or on the pull request branch that triggered the run. Never on your default branch.
- Every change reaches you as a reviewable pull request, either a new one or the one that triggered the run. Kontrua never merges.
- Kontrua does not request the
workflowsscope, so it can never create or edit anything under.github/workflows. It cannot touch your CI or reach your pipeline secrets. - Repository content, including pull request titles, bodies and diffs, is treated as data to describe, never as instructions to follow.
Triggers
Kontrua subscribes to four GitHub events. Three of them do two different things, and the fourth, issue comments, carries the commands described below. Pull request opened, reopened or updated and push to your default branch run the free verdict: no run, no quota, no write to your repository beyond a commit status and at most one comment per pull request.
A pull request approval on your watch branch starts a configured maintenance run, subject to per-file permissions and your allowance. To review a specific newly broken path before approval, use the proposal and apply commands below. Schedules, the API trigger and the repository run button can also start configured maintenance.
Disconnecting and reconnecting
Removing repository access or uninstalling the App pauses audits and corrections. Kontrua retains your run history, audit evidence and document permissions, and the disconnected repository no longer uses a plan slot. Reconnect it from the same workspace to restore access, then choose Enable on its repository page to resume monitoring. Reconnection is subject to your plan limit. To permanently remove the saved repository data, use Remove repository in the repository page's Danger zone.
Commands in pull request comments
Type these commands as comments on the pull request. They need the GitHub App to be subscribed to Issue comment events, which a repository administrator enables once in the App's settings; without it the comment does nothing and everything else keeps working.
@kontrua review@kontrua ignore@kontrua ignore AGENTS.md:41@kontrua correct AGENTS.md:41@kontrua correct AGENTS.md:41 src/new-path.tsProposals require repository write access and Propose corrections or supported Managed generation permission for that file. Kontrua shows the diff and rechecks supported references without writing. Review the surrounding explanation too: a path check does not prove arbitrary prose. Use the proposal ID returned in that response to authorize one of these actions:
@kontrua apply <proposal-id> branch@kontrua apply <proposal-id> headApply checks access, file permission and the current base/head again. A changed revision or revoked permission requires a fresh proposal. This flow supports exact path replacements on open, same-repository GitHub PRs; fork PRs remain read-only. Acceptance and later default-branch verification are recorded separately, with evidence links in the dashboard.
Anyone who can comment can ask for a review. Dismissing needs write access to the repository, the same line GitHub draws for merging: the author of a red pull request is exactly the person with the strongest reason to wave the check away. A dismissal is recorded with the login that made it, follows the claim by file and text rather than by line, and is listed on the repository page in the dashboard with a Restore button next to it. The verdict comment states how many claims are dismissed so a reviewer can see what was set aside.
PR comments
Kontrua posts one comment on the pull request when a correction run starts, then edits that same comment when the run finishes, with what changed and where it landed. On a repository's first run the comment says the whole codebase is being analysed and will take longer than usual. The verdict keeps its own single comment, separate from this one, and posts it only when the pull request breaks or fixes a claim.
Ready to prove your context is true?
Connect your first repository and Kontrua tells you how much of what your docs claim is still true, before it writes anything.