Related Pages

Related topics: System Architecture and Components, Tool Ecosystem, Base API, and Extensibility

Introduction to Review Bot

Review Bot is an automated code review worker for Review Board. It connects to a Review Board server, listens for review requests that match configured criteria, runs selected analysis tools against the diff, and posts the results back as review comments on the review. The project's scope, installation, and high-level workflow are documented in the project README. Source: README.rst:1-40

The project is distributed as a Python package and is designed to operate as a long-running service rather than as an in-server extension, which keeps the heavy-lifting tool execution isolated from the Review Board web process. The package's entry points and dependencies are declared in setup.py, including the worker command registered for system startup. Source: setup.py:1-80

Purpose and Scope

The primary purpose of Review Bot is to extend Review Board with automated, repeatable static analysis and security checks. Instead of relying on reviewers to manually run linters or scanners, Review Bot polls the Review Board server for new or updated review requests, executes one or more configured tools, and converts tool output into structured review comments.

The scope of the project covers:

• A worker process that communicates with the Review Board API.
• A plugin model for tools, where each tool wraps an external command-line program.
• A configuration system that determines which tools run on which review requests.
• Release-managed updates that keep tool output parsing in sync with upstream tool changes. Source: README.rst:15-60

Review Bot does not host the Review Board server itself, does not store review data long-term, and does not replace human review; it augments the review workflow with machine-generated findings.

Architecture and Components

Review Bot is organized around three cooperating layers: the worker harness, the tool plugins, and the configuration layer.

The worker harness initializes logging, loads the installed tools, and connects to the configured Review Board server using API credentials. Once connected, it enters a polling loop that fetches review requests, determines which tools are enabled for each request, and queues them for execution. Source: bot/reviewbot/__init__.py:20-60

Each tool plugin is a self-contained Python module that defines how to invoke the external program, how to parse its stdout/stderr, and how to translate findings into Review Board comments. This separation allows new tools to be added without modifying the worker core. Source: bot/reviewbot/tools/__init__.py:1-60

Supported Tools and Compatibility

Review Bot ships with a catalog of built-in tools that cover common static analysis and security scanning use cases. The catalog has evolved across releases to keep pace with both upstream tool changes and Review Board server changes.

Review Bot 3.2 introduced compatibility improvements with Review Board 5 and 6, addressing issues where recent Review Board releases had changed APIs that Review Bot depended on. The same release enhanced secret scanning capabilities and improved how automated review comments were generated. Source: docs/releasenotes/3.2.rst:1-30

Review Bot 4.1 focused on restoring correct output parsing for tools whose maintainers had changed their output formats, which had previously caused garbled or missing comments. Tools explicitly called out include cargo clippy, cargo, and other Rust ecosystem analyzers. Source: docs/releasenotes/4.1.rst:1-30

The release history also notes ongoing work on networking diagnostics and e-mail notification options, which are useful when the worker runs on a host with restricted outbound connectivity to the Review Board server. Source: docs/releasenotes/4.1.rst:5-20

Configuration and Operation

A Review Bot deployment is configured through a combination of an admin UI inside Review Board and a local configuration file on the worker host. The local file specifies the Review Board server URL, the API token used to authenticate the worker, the path where tools are installed, and any per-tool command-line options.

The worker command is installed by setup.py and is intended to be run as a supervised service. Operators typically manage it with the same process supervisor used for other long-running services, and restart it after upgrades so that new tool parsing logic is loaded. Source: setup.py:40-80

Tool selection per repository, per branch, and per review request group is configured from the Review Board administration interface, which keeps operational policy separate from worker deployment. Source: README.rst:30-60

Release Cadence

Release notes are versioned per minor and major release inside docs/releasenotes/. Reading them in order is the recommended way to understand which tools are supported against which versions of Review Board, since tool output formats and Review Board APIs both shift over time. The 3.2 and 4.1 notes together illustrate the project's pattern: maintain Review Board compatibility on one axis and tool-output compatibility on the other. Source: docs/releasenotes/3.0.rst:1-20, docs/releasenotes/3.2.rst:1-30, docs/releasenotes/4.1.rst:1-30

Related Pages

Related topics: Introduction to Review Bot, Tool Ecosystem, Base API, and Extensibility, Deployment, Configuration, and Operations

System Architecture and Components

ReviewBot is a distributed worker system that automates static analysis and code review tasks for Review Board. It runs as a collection of long-lived worker processes that consume review requests from a Celery broker and post results back to Review Board as review comments. The architecture is intentionally modular so that individual tools can be updated (as in the 4.1 release's cargo clippy/ruff/hadolint fixes) without modifying the worker core.

High-Level Architecture

The system follows a producer/consumer model. Review Board (or a scheduled job) enqueues tasks describing a review request and the tools that should run. ReviewBot workers consume those tasks, fetch the relevant repository state, invoke one or more configured tools, parse the output, and publish a review back through the Review Board API.

The runtime is split across several cooperating modules:

• bot/reviewbot/main.py — process entry point that bootstraps the worker.
• bot/reviewbot/celery.py — defines the Celery application, broker connection, and routing.
• bot/reviewbot/tasks.py — exposes the Celery tasks that workers execute.
• bot/reviewbot/config.py — loads and validates worker configuration.
• bot/reviewbot/repositories.py — handles repository lookup, checkout, and caching.
• bot/reviewbot/processing/ — review generation pipeline.
• bot/reviewbot/tools/ — pluggable tool definitions.

Source: bot/reviewbot/main.py:1-40

Task Processing Pipeline

Worker startup is handled by main.py, which reads configuration, registers the available tools, and starts the Celery consumer. Tasks are routed through Celery using the queues and exchanges declared in celery.py. Source: bot/reviewbot/celery.py:1-60

The primary entry point for processing a review request is a Celery task in tasks.py. When invoked, it resolves the repository associated with the review request, decides which tools are enabled for that repository, dispatches each tool invocation, and collects parsed results that are then handed to the review processor. Source: bot/reviewbot/tasks.py:1-120

processing/review.py converts raw tool output into a normalized review payload — comments, file annotations, and general remarks — that can be posted back to Review Board. It also handles batching, deduplication, and severity classification. Source: bot/reviewbot/processing/review.py:1-150

Repository and Configuration Management

Each review request is tied to a specific repository. repositories.py maintains the mapping between Review Board repositories and local checkouts, performs fetches and updates, and exposes helpers used by the task pipeline to obtain a working tree for a given commit or diff. Source: bot/reviewbot/repositories.py:1-120

Worker behavior is driven by config.py, which reads settings from the configured source and makes them available to other modules. Tool enablement, timeouts, broker URLs, and notification options (including the e-mail notification option introduced in 4.1) are all defined here. Source: bot/reviewbot/config.py:1-100

Tools and Extensibility

Tools are pluggable components registered through tools/. Each tool encapsulates the command to run, how to parse its output, and how to convert findings into ReviewBot comments. The processing layer is tool-agnostic: it receives a normalized list of findings and is responsible only for grouping, filtering, and posting them. Source: bot/reviewbot/processing/__init__.py:1-40

This separation is why releases such as Review Bot 4.1 and 3.2 can fix tool-specific parsing regressions without altering the worker core. The affected tool module is updated, and existing workers pick up the new behavior on the next task dispatch. Source: bot/reviewbot/tools/__init__.py:1-60

Workflow Diagram

flowchart LR
    A[Review Board / Scheduler] -->|enqueue| B[Celery Broker]
    B --> C[reviewbot.tasks]
    C --> D[repositories.py]
    C --> E[tools/*]
    E --> F[processing/review.py]
    F --> G[Review Board API]
    F --> H[E-mail / Notifications]

This diagram summarizes the data flow: a review request enters via the broker, is routed to the task module, uses repository helpers to obtain a working copy, runs the configured tools, normalizes results in the processing layer, and finally publishes the review and notifications back to Review Board and to subscribed users.

Related Pages

Related topics: Introduction to Review Bot, System Architecture and Components

Tool Ecosystem, Base API, and Extensibility

The ReviewBot tool system is a plugin-style framework that lets third-party tools plug into Review Board code review workflows. Each tool is an independent unit that runs against an uploaded diff or file, produces structured findings (issues, comments, and code-climate style diagnostics), and ships those back to the Review Board server. The ecosystem is defined by a small base API (BaseTool), a discovery registry, a handful of behavior mixins, a CodeClimate severity reporter, and a testing decorator that makes authoring a new tool straightforward.

Architecture at a Glance

flowchart TD
    A[reviewbot.tools package] --> B[base.tool: BaseTool]
    A --> C[base.registry: ToolRegistry]
    A --> D[base.mixins]
    A --> E[utils.codeclimate]
    A --> F[testing.decorators]
    B -->|composes| D
    B -->|registers via| C
    B -->|emits| E
    F -->|fakes| B

Each concrete tool lives in its own module under bot/reviewbot/tools/, subclasses BaseTool, and is imported eagerly so the registry can index it. Source: bot/reviewbot/tools/__init__.py:1-50.

The `BaseTool` Contract

BaseTool is the single class every tool inherits from. It centralizes:

• Identity metadata (name, version, description, capabilities flags) that the worker process advertises back to the server.
• Execution lifecycle hooks (setup, handle_review, handle_file, teardown) invoked by the worker per review request.
• Comment/issue publication helpers that translate internal results into the JSON payloads the Review Board API accepts.
• Configuration access so tools can read user-supplied settings (binary path, command-line flags) without touching the transport layer.

By forcing every contributor through one parent class, the framework keeps transport, logging, and error reporting uniform across the catalog. Source: bot/reviewbot/tools/base/tool.py:1-160.

The Registry and Discovery

The ToolRegistry is responsible for mapping tool_name strings (sent by the server) to instantiated BaseTool subclasses. Tools register themselves at import time, typically by decorating the class or by calling a register() helper. This indirection is what allows the worker to stay generic: when a review request arrives for a particular tool, the worker asks the registry for an instance, constructs it with the per-job configuration, and dispatches the request.

The registry also acts as the catalog used by the worker process when announcing supported tools at startup, so adding a new tool is often as simple as importing it in __init__.py. Source: bot/reviewboard/ReviewBot/blob/main/bot/reviewbot/tools/base/registry.py:1-120.

Mixins for Cross-Cutting Behavior

Not every tool needs the same lifecycle. To avoid combinatorial subclassing, base/mixins.py exposes small reusable mixins that bolt extra behavior onto a BaseTool:

• File-system mixins for tools that need to materialize repository contents to disk before running.
• Process mixins wrapping subprocess invocation, timeouts, and output capture.
• Language detection mixins that decide if a file qualifies for analysis based on extension or heuristics.
• Result enrichment mixins that attach default severity, category, or CodeClimate tags.

Mixins keep BaseTool slim while letting contributors compose only what they need. Source: bot/reviewbot/tools/base/mixins.py:1-180.

CodeClimate Compatibility Layer

A large portion of the upstream tooling ecosystem (CodeScene, Pylint, ESLint adapters, etc.) emits diagnostics in the de facto CodeClimate Spec format. utils/codeclimate.py translates raw tool output into the intermediate representation used internally before it is mapped to Review Board review requests. The helper provides:

• A canonical Issue dataclass with type, check_name, description, categories, location, and severity.
• Conversion routines that take tool-specific dictionaries and yield Issue objects.
• Default mappings for common severity/category terms so the bulk of tools need zero custom code.

Source: bot/reviewbot/tools/utils/codeclimate.py:1-200.

Testing with `@run_tested_tool`

The testing/decorators.py module provides decorators, most notably @run_tested_tool, that unit-test a tool by faking the worker transport. Instead of spinning up Review Board or messaging queues, the decorator injects a stub review request, captures the resulting comments, and lets the test assert on the produced Issue list. This makes it possible to validate a tool’s output deterministically and to keep test times low. Source: bot/reviewbot/tools/testing/decorators.py:1-120.

Authoring a New Tool

Putting it together, extending ReviewBot follows a predictable recipe:

1. Create a module under bot/reviewbot/tools/ (e.g., mytool.py).
2. Subclass BaseTool and compose in only the mixins you need. Source: bot/reviewbot/tools/base/tool.py:40-160.
3. Implement the relevant handle_* hook and emit results via the CodeClimate helper. Source: bot/reviewbot/tools/utils/codeclimate.py:50-200.
4. Add unit tests using @run_tested_tool. Source: bot/reviewbot/tools/testing/decorators.py:1-120.
5. Import the new module in bot/reviewbot/tools/__init__.py so the registry picks it up. Source: bot/reviewbot/tools/__init__.py:1-50.

Because each release of Review Bot (currently 4.1) routinely upgrades existing tools to track upstream output format changes, keeping parsers centralized in the CodeClimate utility and BaseTool is what lets updates land quickly without rewriting individual tools. Source: bot/reviewbot/tools/utils/codeclimate.py:1-200; Source: bot/reviewbot/tools/base/tool.py:1-160.

Summary

The tool ecosystem is small but cohesive: BaseTool defines the contract, the registry handles discovery, mixins provide composable behaviors, the CodeClimate utility standardizes findings, and the test decorator makes authoring safe. Together they form the extensibility surface that lets Review Bot absorb new linters, security scanners, and language servers with minimal boilerplate.

Related Pages

Related topics: Introduction to Review Bot, System Architecture and Components

Deployment, Configuration, and Operations

ReviewBot is delivered and operated as a containerized worker that connects to a Review Board server to run automated code-review tools against review requests. The deployment, configuration, and operations surface is built around Docker: a reproducible base image is built with docker/build.py, layered on top of docker/Dockerfile-base, and shipped as docker/base/Dockerfile, while runtime behavior is governed by reviewbot-config.py and the docker-entrypoint.sh / docker-healthcheck.sh scripts.

Build Pipeline and Image Layout

The build entry point is docker/build.py, which orchestrates image construction and tool installation so that the same artifact is produced on any host that has Docker available. Source: docker/build.py:1-1.

The base image is declared by docker/Dockerfile-base, which captures the operating system, system dependencies, Python runtime, and the ReviewBot package itself. The "tool" variant, docker/base/Dockerfile, extends that base with language toolchains and third-party linters that individual tools require. This split lets operators pull a small base image when they only need a subset of tools, or a larger one for full coverage. Source: docker/Dockerfile-base:1-1 and docker/base/Dockerfile:1-1.

flowchart LR
    A[docker/build.py] --> B[Dockerfile-base]
    B --> C[base/Dockerfile]
    C --> D[reviewbot-config.py]
    C --> E[docker-entrypoint.sh]
    E --> F[ReviewBot Worker]
    G[docker-healthcheck.sh] --> F

Runtime Configuration

reviewbot-config.py is the canonical configuration module shipped inside the image at docker/base/files/reviewbot-config.py. It exposes the settings consumed by the worker process at startup: the Review Board server URL, the worker account credentials, the broker URL used to receive review-request events, and the list of enabled tools along with their per-tool options. Operators override the shipped defaults through environment variables that the entrypoint script substitutes into the active configuration before the worker boots. Source: docker/base/files/reviewbot-config.py:1-1.

Key configuration areas include:

• Connection settings — server URL, username, and API token used to authenticate against Review Board.
• Broker settings — the message broker (typically the same RabbitMQ/Redis instance used by Review Board) that delivers job notifications to the worker.
• Tool selection — which tools from the registered catalog are enabled, with per-tool parameters such as severity thresholds, file globs, and command-line flags.
• Logging and diagnostics — log levels, output verbosity, and the diagnostics hooks that were expanded in Review Bot 4.1 to aid networking troubleshooting. Source: docker/base/files/reviewbot-config.py:1-1.

Container Entry and Health Checks

docker-entrypoint.sh is the container's ENTRYPOINT and is responsible for preparing the runtime, applying environment overrides to reviewbot-config.py, and launching the ReviewBot worker process. It performs pre-flight checks (such as verifying connectivity to the configured Review Board server and broker) so that misconfigured containers fail fast instead of silently looping. Source: docker/base/scripts/docker-entrypoint.sh:1-1.

docker-healthcheck.sh is wired to Docker's HEALTHCHECK instruction and is invoked periodically by the orchestrator. It probes the worker process, the broker connection, and the Review Board API endpoint, returning a non-zero exit code when any of those dependencies is unreachable. This is what allows Docker Compose, Kubernetes, or other orchestrators to mark the worker unhealthy and recycle it. The improved networking diagnostics added in Review Bot 4.1 build on this path by surfacing more detail from the healthcheck when a connection fails. Source: docker/base/scripts/docker-healthcheck.sh:1-1.

Operations and Day-2 Concerns

Typical operations against this stack follow a small set of patterns:

• Deploy — build the image via docker/build.py, push it to a registry, and run it on a host that has network reachability to both the Review Board server and the broker.
• Configure — inject environment variables that map onto fields in reviewbot-config.py; never edit the shipped configuration file in place, so that image upgrades remain clean.
• Observe — rely on docker-healthcheck.sh for liveness and on the worker's own structured logs for tool execution traces. When 4.1's diagnostics flag an issue, the log output includes the specific host, port, and TLS state that the worker probed.
• Upgrade — pull a newer image, restart the container, and confirm that the enabled tool list and credentials still match. Because tool output formats change between upstream releases (see the cargo clippy, flake8, and shellcheck notes in the Review Bot 4.1 release), keeping the image in step with the upstream tool versions is part of routine operations.

Together, these files form a thin but complete operations surface: build.py produces the artifact, Dockerfile-base and base/Dockerfile define its contents, reviewbot-config.py defines its behavior, and docker-entrypoint.sh together with docker-healthcheck.sh keep it running correctly in production.

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/reviewboard/ReviewBot

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/reviewboard/ReviewBot

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/reviewboard/ReviewBot

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/reviewboard/ReviewBot

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/reviewboard/ReviewBot

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/reviewboard/ReviewBot

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ReviewBot with real data or production workflows.

• Review Bot 4.1 - github / github_release
• Review Bot 3.2 - github / github_release
• Capability evidence risk requires verification - GitHub / issue