Keldyn Review Bot

The Keldyn Review Bot reviews every pull request on a connected repository against your code-level controls: organization frameworks plus the frameworks of the use cases the repository is bound to (all of them by default). 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 for open pull requests. Verdicts are flags for people to act on and never change a control’s status. When a pull request is merged and a later review of that same PR recorded pass for a control that had previously failed or been at risk, the bot appends one evidence entry (merged commit and a short description). It never replaces an existing entry. A merged pull request that names a Keldyn task can also close that task; see Linking pull requests to tasks. For read-only source-control evidence (access, branch protection, PR approvals, CI history), use the separate GitHub integration.

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.

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 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. That is a coverage gap, not a finding that merging puts the control at risk.

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

Before you begin

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.

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.

The bot never commits

The bot reads the pull request and proposes fixes as comments. It never commits, pushes, or edits the branch.

Set up the integration

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

GitHub

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.

Authorize your GitHub account

Complete the GitHub authorization request. Keldyn uses it to verify that your account can access the installation.

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.

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.

Keldyn Web Security

On GitHub, also install the Keldyn Web Security action from the GitHub Marketplace. It scans the repository for SAST issues, vulnerable dependencies, leaked secrets, and configuration problems. The Review Bot still posts Keldyn Controls Review against your code-level controls. A workflow with no API key still scans and does not call Keldyn. To open findings and remediation tasks in Keldyn, create a team API key and store it as the KELDYN_API_KEY repository secret. Open User settings → Team → API Keys and create a key. Turn on Submit automated evidence (evidence.submit). That is the permission this scan needs. A key that already has Edit GRC records (grc.write) can submit scans too, so you do not need a second key for that. evidence.submit does not include the rest of GRC:

Submit a Web Security scan for the team.
Create and update findings.
Create and update the remediation task attached to a new finding.

That key does not need access to controls, control evidence, Review Bot settings, or anything outside this ingest. Add a workflow file such as .github/workflows/web-security.yml:

name: Web Security

on:
  pull_request:
  schedule:
    # Runs from the default branch only. GitHub may start it later than 07:00 UTC.
    - cron: "0 7 * * *"

permissions:
  contents: read

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: keldynai/web-security@v1
        with:
          keldyn-api-key: ${{ secrets.KELDYN_API_KEY }}

Leave keldyn-api-key unset and the scan stays in GitHub. To gate merges, require its check on the default branch the same way as Keldyn Controls Review. Inputs, the ignore file, and what each scanner covers are on the Marketplace page.

GitLab

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).

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.

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.

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.

Bitbucket

Create an access token

Create a Bitbucket Cloud workspace or repository access token with Repositories: Read and Pull requests: Write.

Connect in Keldyn

On the Bitbucket card, select Connect Bitbucket. Paste the token. Keldyn generates a webhook secret: leave it as-is.

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, fulfilled, and comment created.

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 summary titles a warning as a fail. This does not fail the merge check.
Maximum inline comments per review	20	Findings beyond this appear only in the summary comment

Repositories and use cases

Not every repository serves every use case. The Repositories card lists one row per repository the bot knows about (every repository you have bound, plus every repository that has had a review), the use cases it is bound to, and its last review. Bind a repository to one, several, or all of your use cases. On every review the bot loads your organization’s code-level controls plus the code-relevant controls of the frameworks assigned to exactly those use cases. A repository without a binding is reviewed against all use cases.

One use case: a service repository that implements a single AI system.
Several use cases: a monorepo or shared platform that several systems depend on.
All use cases: the default; also the right choice for shared infrastructure.

To bind a repository, open its use-case picker, untick All use cases, tick the use cases it serves and click Save. To bind a repository before its first pull request, use Add repository with the full path as the provider shows it (owner/repository, or group/subgroup/project on GitLab). Reset to all removes a binding. Each row also has Review and Block:

Review (on by default): when off, automatic reviews are skipped for that repository. @keldyn still runs.
Block (off by default): when on, the two rule-based checks (secrets in the change, and high-risk / VA-style patterns) can fail the Keldyn Controls Review check. Model findings stay advisory and never block.

Bindings are held in Keldyn, not in your repository, and take effect on the next review. Changing a binding is recorded in your organization’s audit trail alongside other integration changes.

How a review works

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.

Controls are loaded from Keldyn

The bot reviews every code-relevant control on the organization, plus code-relevant controls from the frameworks assigned to the use cases the repository is bound to (all use cases unless you bound it, see Repositories and use cases): excluding controls marked not applicable.

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.

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.

How the check is marked:

Block off (default): the check succeeds. Model findings and rule-based hits are posted on the pull request but never stop a merge.
Block on: the check fails only when a rule-based check fails (secrets or high-risk change). A review that cannot finish also fails the check, so an unreviewed change cannot sneak through a required gate.
The summary title still reports model merge impact (These changes do not put controls at risk / Merging may put control(s) at risk / Merging would cause control(s) to fail). That title is not the merge gate.

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 uses in your IDE.

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. When the pull request is merged and it resolved a finding (a later review of that PR recorded pass after an earlier fail or warning), the bot appends one evidence entry with the merged commit. Use the history to see what merging would have done. If a finding is still open, update the control yourself, or through the controls-to-code workflow.

Linking pull requests to tasks

Put a task reference such as TSK-012 in the pull request’s branch name, title, or description. The bot links the pull request to that task in your Keldyn organization when the pull request opens or updates. The link is made even when automatic review is off, or the review is skipped for plan or token limits. One task can have several pull requests, and one pull request can name several tasks. References to tasks in another organization are ignored. During the review, Keldyn also decides how far the change completes each linked task, against the acceptance criteria of the task’s controls: criteria met, partly done, or not addressed. The summary comment lists each task and what merging will do. This is part of the same screening call the review already makes. It is not a separate model call. When the pull request is merged, Keldyn uses the review of the merged commit. It does not re-review:

Review result for the merged commit	What happens to the task
Criteria met, and no linked control would fail	The task is closed. The pull request and the review’s summary are added to each linked control’s evidence, and the control’s evidence is re-checked.
Criteria met, but a linked control would fail	The task moves to In progress.
Partly done	The task moves to In progress. A later pull request for the same task can finish it.
Not addressed, not reviewed, or new commits after the last review	The task is unchanged. Mention `@keldyn` to review the latest commit before merging.

The task shows its linked pull requests and their review result. Closing a task this way re-checks its controls the same way as closing it by hand: a control moves to Implemented only when its evidence passes the sufficiency check.

Coding agents that use the Keldyn MCP server are told to put the task reference in the branch name or PR title, so you do not have to ask.

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 (path and line only), and optional suggested fix	Posted on the pull request and stored in Review history. Source snippets may appear on the pull-request comment; Keldyn does not keep them after the verdict.

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. The review sends the changed lines, the version identifiers, and the use case id. The pull-request head checkout is discarded when the run finishes, and nothing of the changed lines is kept after the verdict. What leaves your pipeline, where it goes, who can see it, and how long it is kept are on Data flow.

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 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.
Review off for the repository: automatic reviews skip that repository. Comment @keldyn to run once.
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

Developer SDLC playbook

Run the same review rules in your IDE with review-changes before you open a pull request.

From controls to code

Turn a Review Bot finding into updated evidence or a remediation task.

Keldyn Web Security

Install this GitHub Action too. It scans the repository each day and on pull requests for SAST issues, vulnerable dependencies, leaked secrets, and configuration problems. When you create the team API key, turn on Submit automated evidence (evidence.submit). A key with Edit GRC records (grc.write) can submit scans too.

GitHub evidence

Collect read-only source-control evidence. A separate GitHub App from this one.

Keldyn MCP server

Connect Claude Code or Cursor so local reviews use the same control set.

Home

Getting started

Integrations

AI Tooling

Guides

Security & compliance

Keldyn Review Bot

What it’s used for

Before you begin

Set up the integration

GitHub

Keldyn Web Security

GitLab

Bitbucket

Review settings

Repositories and use cases

How a review works

Review history

Linking pull requests to tasks

What data Keldyn collects and why

Permissions

Troubleshooting

Next steps

Developer SDLC playbook

From controls to code

Keldyn Web Security

GitHub evidence

Keldyn MCP server

​What it’s used for

​Before you begin

​Set up the integration

​GitHub

​Keldyn Web Security

​GitLab

​Bitbucket

​Review settings

​Repositories and use cases

​How a review works

​Review history

​Linking pull requests to tasks

​What data Keldyn collects and why

​Permissions

​Troubleshooting

​Next steps

Developer SDLC playbook

From controls to code

Keldyn Web Security

GitHub evidence

Keldyn MCP server

What it’s used for

Before you begin

Set up the integration

GitHub

Keldyn Web Security

GitLab

Bitbucket

Review settings

Repositories and use cases

How a review works

Review history

Linking pull requests to tasks

What data Keldyn collects and why

Permissions

Troubleshooting

Next steps