> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keldyn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Keldyn Review Bot

> Review every pull request against your code-level controls before merge. Posts a Keldyn Controls Review check, inline findings, and suggested fixes on GitHub, GitLab, and Bitbucket.

The Keldyn Review Bot reviews every pull request on a connected repository against your **code-level controls** — organization frameworks plus every framework assigned to a use case. It posts a **Keldyn Controls Review** check you can require before merge, a summary comment with a per-control table, and inline findings with suggested fixes. Comment `@keldyn` on a pull request to run an on-demand review.

This is **not** an evidence integration. Verdicts are flags for people to act on. They never change a control's status or evidence in Keldyn. For read-only source-control evidence (access, branch protection, PR approvals, CI history), use the separate [GitHub](/integrations/github) integration.

<Note>
  Integrations are typically managed by workspace admins. The Review Bot GitHub
  App is a **different** app from the GitHub evidence integration. This one
  posts checks and comments on pull requests; the evidence app only reads.
</Note>

## What it's used for

The bot answers one question for every code-relevant control: **would merging this pull request cause the control to fail?**

It is not a generic code review. It does not judge whether the repository already satisfies a control, and it raises no bug, style, or performance findings unless a listed control requires them. A pre-existing gap in code the pull request does not touch is not a finding.

The same review rules as the MCP [`review-changes`](/guides/developer-compliance-sdlc#5-review--before-you-commit-or-open-a-pr) prompt apply, so an IDE review and a pull-request review judge the same way. Adding a control in Keldyn, or assigning a framework to a use case, changes the next review with no extra setup.

| Verdict           | What it means on the pull request                                            |
| ----------------- | ---------------------------------------------------------------------------- |
| **Would fail**    | Merging would cause this control to fail                                     |
| **At risk**       | Merging may put the control at risk, or the change is demonstrably ambiguous |
| **Unaffected**    | Merging would not put this control at risk                                   |
| **N/A**           | The control is not about this code (for example an org-wide process control) |
| **Not evaluated** | The review did not record a verdict for this control                         |

Controls you have marked not applicable in Keldyn are left out of the review.

## Before you begin

<Steps>
  <Step title="Decide which platforms to connect">
    One integration covers GitHub, GitLab, and Bitbucket. Connect only the
    platforms you host code on. You can add another later without disconnecting
    the first.
  </Step>

  <Step title="Choose the repositories to include">
    On GitHub, pick the organization and repositories during App installation.
    On GitLab and Bitbucket, the access token's scope is what the bot can
    review — use a project, group, workspace, or repository token that covers
    only those repos.
  </Step>

  <Step title="The bot never commits">
    The bot reads the pull request and proposes fixes as comments. It never
    commits, pushes, or edits the branch.
  </Step>
</Steps>

## Set up the integration

In the Keldyn web app, go to **Integrations** and select **Keldyn Review Bot**. Connect each provider you need.

### GitHub

<Steps>
  <Step title="Install the Review Bot GitHub App">
    Select **Install GitHub App**. GitHub opens the Keldyn Review Bot
    installation flow. Choose the organization and repositories to review,
    review the requested permissions, and approve the installation.
  </Step>

  <Step title="Authorize your GitHub account">
    Complete the GitHub authorization request. Keldyn uses it to verify that
    your account can access the installation.
  </Step>

  <Step title="Confirm the check appears">
    Open a pull request on an included repository (or comment `@keldyn` on an
    existing one). The **Keldyn Controls Review** check should appear on the
    head commit, with a summary comment on the pull request.
  </Step>
</Steps>

<Tip>
  To gate merges, add **Keldyn Controls Review** as a required status check on
  the default branch (GitHub branch protection or rulesets). If a review cannot
  finish, the check fails so an unreviewed change cannot merge behind a required
  check.
</Tip>

### GitLab

<Steps>
  <Step title="Create an access token">
    Create a project or group access token with the **Developer** role and the
    `api` scope (read the repository, write merge-request notes and commit
    statuses). For a self-managed instance, note the base URL (for example
    `https://gitlab.example.com`).
  </Step>

  <Step title="Connect in Keldyn">
    On the GitLab card, select **Connect GitLab**. Paste the token and, for
    self-managed GitLab, the base URL. Keldyn generates a webhook secret —
    leave it as-is.
  </Step>

  <Step title="Add the webhook">
    After connecting, copy the **Webhook URL** and the **webhook secret**
    (shown once). In GitLab, add a project or group webhook with that URL and
    secret token, subscribed to **Merge request** events and **Comments**.
  </Step>
</Steps>

<Warning>
  The webhook secret is shown once. Paste it into GitLab immediately. If you
  lose it, use **Rotate token** to generate a new secret and update the
  webhook.
</Warning>

### Bitbucket

<Steps>
  <Step title="Create an access token">
    Create a Bitbucket Cloud workspace or repository access token with
    **Repositories: Read** and **Pull requests: Write**.
  </Step>

  <Step title="Connect in Keldyn">
    On the Bitbucket card, select **Connect Bitbucket**. Paste the token.
    Keldyn generates a webhook secret — leave it as-is.
  </Step>

  <Step title="Add the webhook">
    After connecting, copy the **Webhook URL** and the **webhook secret**
    (shown once). In Bitbucket, add a repository webhook with that URL and
    secret, subscribed to **Pull request created**, **updated**, and
    **comment created**.
  </Step>
</Steps>

GitLab and Bitbucket receive the same result as a commit / build status named **Keldyn Controls Review**. Require that status in your merge checks the same way you would a CI job.

## Review settings

Settings apply to every connected provider on the next review. Open the **Review settings** card on the integration page.

| Setting                                                  | Default | What it does                                                                      |
| -------------------------------------------------------- | ------- | --------------------------------------------------------------------------------- |
| **Review automatically on pull request open and update** | On      | Off: reviews only when someone comments `@keldyn`                                 |
| **Review draft pull requests**                           | Off     | Off: drafts are skipped until they are marked ready for review                    |
| **Treat warnings as failures**                           | Off     | On: the merge check fails when any control reports a warning or was not evaluated |
| **Maximum inline comments per review**                   | 20      | Findings beyond this appear only in the summary comment                           |

## How a review works

<Steps>
  <Step title="A pull request opens or updates">
    The bot starts on open, push, reopen, and ready-for-review. Comment
    `@keldyn` (optionally with instructions, for example
    `@keldyn focus on the auth changes`) to re-run at any time.
  </Step>

  <Step title="Controls are loaded from Keldyn">
    The bot reviews every code-relevant control on the organization, plus
    code-relevant controls from every framework assigned to a use case —
    excluding controls marked not applicable.
  </Step>

  <Step title="The pull request is reviewed">
    Keldyn reads the diff and records one verdict per control, with file and
    line evidence for anything that would fail or is at risk.
  </Step>

  <Step title="Results are posted on the pull request">
    One summary comment is created or updated in place (per-control table,
    evidence, suggested fixes). Inline comments land on changed lines, with
    suggested edits where a concrete fix exists. The
    **Keldyn Controls Review** check completes on the head commit.
  </Step>
</Steps>

How the check is marked:

* Any **Would fail** → the check **fails**
* Only warnings or unevaluated controls → the check is **neutral** (or **fails** when **Treat warnings as failures** is on)
* Every applicable control **Unaffected** → the check **succeeds**
* The review itself cannot finish → the check **fails**

<Info>
  For controls already marked Implemented, the bot treats a change that weakens
  or removes the previously recorded evidence as a regression. That is the same
  rule [`review-changes`](/guides/mcp-controls-to-code) uses in your IDE.
</Info>

## Review history

The **Review history** card on the integration page lists every run: repository, pull request, overall result, per-control tally, whether it ran automatically or from `@keldyn`, and time. Expand a row for each control's verdict and evidence.

Verdicts in this history do not change a control's status in Keldyn. Use them to see what merging would have done, then update controls yourself — or through the [controls-to-code workflow](/guides/mcp-controls-to-code) — when a finding is real.

## What data Keldyn collects and why

The bot requests only the access needed to read the pull request, post results, and record the run.

| Data collected                 | What it contains                                                             | Why it is collected                                       |
| ------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Pull-request metadata**      | Repository, number, title, head commit, and pull-request URL                 | To start the review and link the run back to the change   |
| **Pull-request head and diff** | The checked-out head commit and the diff against the base                    | So the review can judge merge impact against each control |
| **Control set**                | Code-relevant controls and their review criteria from your Keldyn workspace  | What the review is judged against                         |
| **Review results**             | Per-control verdict, summary, file/line evidence, and optional suggested fix | Posted on the pull request and stored in Review history   |

<Note>
  The bot never commits, pushes, or edits the pull-request branch. Access
  tokens and webhook secrets for GitLab and Bitbucket are stored encrypted.
  The webhook secret cannot be read back after the page that first showed it.
  GitHub uses short-lived installation tokens; Keldyn stores the installation
  id, not a per-user token.
</Note>

### Permissions

**GitHub App** (Keldyn Review Bot — not the evidence app):

| Permission        | Access         | Purpose                                                         |
| ----------------- | -------------- | --------------------------------------------------------------- |
| **Checks**        | Read and write | Open and complete **Keldyn Controls Review** on the head commit |
| **Contents**      | Read           | Read the pull-request head                                      |
| **Pull requests** | Read and write | Read the diff; post the summary and inline comments             |
| **Metadata**      | Read           | Discover included repositories                                  |
| **Issues**        | Read and write | Acknowledge `@keldyn` comments                                  |

**GitLab** — Developer-role token with the `api` scope, so the bot can read the repository and write merge-request notes and commit statuses.

**Bitbucket Cloud** — **Repositories: Read** and **Pull requests: Write**.

## Troubleshooting

Reviews that never start, or a check that stays pending, usually mean one of the following:

* **Wrong GitHub App** — the evidence [GitHub](/integrations/github) integration is connected, but this page's Review Bot App is not. Install **Keldyn Review Bot** from this integration, not from GitHub evidence.
* **Repository not included** — the GitHub App installation does not include the repository, or the GitLab / Bitbucket token cannot see it.
* **Webhook missing or stale** — GitLab and Bitbucket need the URL and secret from the provider card. After **Rotate token**, update the webhook secret on the provider.
* **Draft pull request** — drafts are skipped unless **Review draft pull requests** is on. Mark the pull request ready, or comment `@keldyn`.
* **Automatic review off** — with **Review automatically** off, nothing runs until someone comments `@keldyn`.
* **No code-level controls** — the check reports that there is nothing to review against. Assign a framework with code-relevant controls, or stop marking those controls not applicable.
* **Check not required** — the review ran but merges are not blocked. Add **Keldyn Controls Review** as a required status check (GitHub) or required commit / build status (GitLab, Bitbucket).

If the GitHub installation was suspended or removed, select **Install GitHub App** again. Removing one provider leaves the others connected; **Disconnect all providers** removes every connection.

## Next steps

<CardGroup cols={2}>
  <Card title="Developer SDLC playbook" icon="waypoints" href="/guides/developer-compliance-sdlc" arrow={true}>
    Run the same review rules in your IDE with `review-changes` before you open
    a pull request.
  </Card>

  <Card title="From controls to code" icon="git-compare-arrows" href="/guides/mcp-controls-to-code" arrow={true}>
    Turn a Review Bot finding into updated evidence or a remediation task.
  </Card>

  <Card title="GitHub evidence" icon="github" href="/integrations/github" arrow={true}>
    Collect read-only source-control evidence. A separate GitHub App from this
    one.
  </Card>

  <Card title="Keldyn MCP server" icon="plug" href="/keldyn-mcp-server" arrow={true}>
    Connect Claude Code or Cursor so local reviews use the same control set.
  </Card>
</CardGroup>