How it works

This page follows a pull request from the webhook to the published comment, and then shows how triage, replies, fixes and analytics fit around it. It explains the terms you meet in the web app; the details of each feature are on its own page.

The flow at a glance

Pull request opened or updated on the code host
        │ webhook
        ▼
Review run
  ├─ context from the repository
  ├─ finder and verifier (your models)
  ├─ deterministic scanners (sandbox, optional)
  └─ findings, ranked and filtered by the policy
        │
        ▼
Mode of the repository
  ├─ Off ........ no review
  ├─ Shadow ..... result stays in the web app
  ├─ Approval ... waits in the approvals inbox until someone approves
  └─ Automatic .. published at once
        │
        ▼
Outbox → publisher → summary, inline comments and status on the code host

From code host to organisation

1. Installation. On GitHub, an instance admin registers a GitHub App and installs it on an organisation or on single repositories. Other code hosts (GitLab, Azure DevOps, Bitbucket, Gitea, Forgejo) are added by an organisation admin as a connection with an access token (Code hosts).
2. Organisation. Every installation and connection belongs to an organisation in CodeLotse, also called a tenant. The organisation holds the members, model keys, rules and settings, and its data is isolated from other organisations in the database.
3. Repositories. Each repository the app can access appears under Repositories. A repository has a Policy: the mode and settings for each feature, either its own or the organisation defaults.
4. Events. The code host sends webhooks for pull requests, issues, comments and pushes. CodeLotse stores each delivery once and turns it into a job through a transactional outbox, so no event is lost and nothing runs twice.

The review run

A review run starts when a pull request is opened, when it gets a new commit, when a draft is marked ready for review and when someone writes re-review. Draft pull requests are only reviewed when the policy says so.

Step	What happens
Context	CodeLotse checks out the head commit in a temporary workspace and collects the diff, the files it imports, definitions and callers of changed code, similar code from the code index, earlier pull requests and the rules that apply. The workspace is deleted after the run.
Finder	A model of the strong tier reads the diff in parts and proposes candidate findings. Candidates that do not point into the diff are rejected.
Verifier	A second pass checks each candidate against the code and confirms, downgrades or rejects it.
Deterministic checks	When turned on, scanners such as Gitleaks, ast-grep or Bandit run in the sandbox and their findings join the review.
Ranking	Duplicates of earlier comments are removed, learnings and suppressions are applied, and the policy filters by minimum severity, minimum confidence and the maximum number of comments.
Summary	A model of the standard tier writes the summary. On a new commit, threads of findings that are now fixed are marked for resolution.

Each finding has a severity (Critical, High, Medium, Low, Nit), a category (Bug, Security, Performance, Maintainability, Tests, Documentation, Style, Rule) and a confidence. Critical and high findings count as blocking.

The light code

Every review and pull request in the web app carries a state, drawn as two lights. You can choose plain or nautical words in the account menu (The web app).

Light	Plain	Nautical	Meaning
White, aligned	No issues	On course	Reviewed, nothing to do
Amber, slight offset	Worth a look	Drifting	Only advisory findings are open
Red, wide offset	Changes needed	Off course	A critical or high finding is open
White over red	Reviewing	Aboard	CodeLotse is working
Hollow	Inactive	In port	Failed, skipped or turned off

Modes

Every feature has a mode in the repository policy. Reviews, triage, replies, commands, CI analysis, pull request descriptions and draft fixes use these four:

Mode	Effect
Off	Nothing runs.
Shadow	The feature runs and its result is visible in the web app. Nothing is posted to the code host. Recommended to start.
Approval	The result waits in Approvals until someone with the right role posts or rejects it.
Automatic	The result is posted right away.

Some features have their own modes: learning, deterministic checks and acceptance criteria use Off, Shadow and On; the code index uses Off, Lexical and Hybrid; assignment uses Off, Shadow, Suggest and Apply. On public repositories, replies, answers to questions, CI analyses and draft fixes always wait for approval, even when the mode is Automatic.

Publishing

Nothing reaches the code host except through the publisher:

• An approved or automatic output becomes a publish intent in the outbox. The publisher posts it once, even when a job is retried.
• Before it posts a review, the publisher checks that the pull request still has the reviewed head commit. If a newer commit arrived, the old review is skipped.
• Reviews are posted as one review with a summary and inline comments where the code host supports that, plus a status on the head commit named CodeLotse. See Pull request reviews and the feature parity matrix.
• An output that waits for approval expires after seven days.

Around the review

Feature	Trigger	Result
Issue triage	An issue is opened or its text edited	Labels from the allowlist, a priority, possible duplicates, a request for missing information
Replies	An issue is opened or gets a new comment	One grounded answer, workaround or clarification, or nothing
Commands	A mention of the bot in a pull request comment	An explanation, a suggested fix, an ignored finding, a new review or an answer
Fix runs	A maintainer comments fix on an issue or adds a trigger label	A draft pull request built and tested in the sandbox
CI failure analysis	A check of an open pull request fails	One comment that explains the failure
Reviewer suggestions	A pull request or issue is opened	Suggested reviewers or assignees with reasons

The sandbox is a separate runner that executes repository code, scanners, tests and linters in gVisor or Firecracker. It only pulls signed jobs, has no inbound port and never sees your database, encryption keys or code host tokens (Sandbox).

Learning and analytics

CodeLotse reads how people react to its comments: resolved threads, committed suggestions, ignore commands, rejected approvals and, on private repositories, reactions. From that it calibrates confidence and proposes suppressions for findings that are dismissed most of the time. A maintainer activates a suppression before it applies, and it expires. See Rules, suppressions and learnings.

Analytics roll these outcomes up per hour, at team level only.

Data and privacy

• Model calls go only to the provider and endpoint your organisation configured, with your key. They contain the diff, context from the repository and pull request or issue text (Models and keys).
• Source code is not stored at rest, except in the code index when you turn it on, in the patches of fix runs and in the lines that suggestions replace (Data inventory).
• Tenant isolation: every table with organisation data is protected by PostgreSQL row-level security per organisation. Secrets such as model keys are encrypted.
• People: analytics and reviewer suggestions have their own privacy rules (Assignment and privacy, Team analytics).
• Audit: every change in the web app is written to an audit log.

Related

• Glossary
• Threat model
• Architecture decision records