Related Pages

Related topics: Supported Code Checking Tools & Configuration, Deployment & Infrastructure

ReviewBot Overview & System Architecture

Purpose and Scope

Review Bot automates parts of the code review process by integrating a wide range of industry-standard static analysis and code checking tools with Review Board. It is designed to run external tools over the files attached to a review request, parse their output, and post the results back to Review Board as a review with comments. According to the project overview, Review Bot is made for Review Board, scalable (built on Celery), and extensible through a plugin API. Source: README.rst:7-25.

The repository is split into two independently distributed Python packages that work together:

Source: bot/README.rst:11-23, extension/README.rst:9-19.

System Components

Review Board Extension

The extension lives at extension/reviewbotext/ and is loaded into Review Board. It surfaces the configuration UI used by administrators to select and parameterize code checking tools. The form layer in extension/reviewbotext/forms.py defines integration options such as max_comments (the upper bound on the number of comments a tool may post in a single review) and the new notify_owner_only flag added in 4.1 to restrict e-mail notifications to the review request owner. Source: extension/reviewbotext/forms.py:38-65.

Worker

The worker is the execution engine. It is distributed as the reviewbot-worker Python package and is registered as console script reviewbot-worker in the package entry points. Source: bot/setup.py:39-58. The worker pulls tasks from a Celery broker, fetches the relevant files from Review Board via its HTTP API, dispatches them to a configured tool, and posts the resulting review back.

High-Level Architecture

flowchart LR
    A[Review Board Server] -->|POST review request| B[Review Bot Extension]
    B -->|Schedule job via Celery| C[Celery Broker]
    C --> D[Review Bot Worker]
    D -->|Fetch files via API| A
    D -->|Invoke tool| E[Code Checking Tool]
    E -->|stdout / report| D
    D -->|Post review| A
    A -->|E-mail notification| F[Reviewer / Owner]

The worker is tool-agnostic: it loads any number of tool plugins that share a common base class. The package entry_points configuration registers each available tool under the reviewbot.tools group. Source: bot/setup.py:39-58.

Tool Plugin Model

All tools inherit from BaseTool, which is re-exported from the convenience package reviewbot.tools.base. Three reusable mixins are also exported from that package and are commonly combined with BaseTool:

Source: bot/reviewbot/tools/base/__init__.py:1-22.

Tool authors subclass BaseTool (optionally with a mixin), declare class attributes such as name, version, description, timeout, exe_dependencies, and file_patterns, and implement build_base_command to construct the command line that is executed. Examples of declarative options can be seen in bot/reviewbot/tools/clang.py:21-44 for Clang Static Analyzer, bot/reviewbot/tools/jshint.py:22-58 for JSHint, and bot/reviewbot/tools/cargotool.py:19-46 for the Cargo tool. Each tool uses Django form fields (django.forms.CharField, BooleanField, ChoiceField, etc.) for its options, so the extension can render them automatically in the Review Board admin UI.

Working With Full Repositories

Some tools (Clang, Cargo, Go, etc.) need a full source checkout to build or resolve imports. FullRepositoryToolMixin and the repository abstraction in bot/reviewbot/repositories.py handle this. BaseRepository is the base class and stores name, clone_path, and a local repo_path under the per-user data directory returned by appdirs.site_data_dir('reviewbot'). Source: bot/reviewbot/repositories.py:30-58.

Configuration and Extensibility

The entry_points mechanism is the extension point for adding new tools. The shipped list registers 20 tools, covering languages such as C/C++ (clang, cppcheck, cpplint, fbinfer), Python (flake8, pycodestyle, pydocstyle, pyflakes, doc8), JavaScript (jshint), Java (checkstyle, pmd), Go (gotool, gofmt), Ruby (rubocop), Rust (cargotool, rustfmt), and shell scripts (shellcheck), plus a rbsecretscanner integration. Source: bot/setup.py:39-58.

Two additional layers complete the system:

• Testing harness — bot/reviewbot/tools/testing/testcases.py exposes tool_class-driven helpers such as _can_handle_file so that tool authors can unit-test file filtering without spinning up the full worker.
• Admin-side forms — The extension form layer governs global options that apply across all tools, including max_comments and the 4.1-era notify_owner_only notification preference. Source: extension/reviewbotext/forms.py:38-65.

Release History Notes

The most recent release tracked in the community evidence is Review Bot 4.1, which restored parsing for cargo clippy, cargo test, and other tools whose output formats had drifted, added a new e-mail notification option, and improved networking diagnostics. Review Bot 3.2, the prior release, focused on Review Board 5/6 compatibility and Secret Scanning enhancements. Both releases highlight the worker's role as the single integration point between arbitrary external tools and Review Board's review API. Source: GitHub Release 4.1, GitHub Release 3.2.

See Also

• Review Bot Documentation
• Review Board Integrations
• Celery Documentation
• Related projects: RBTools, RB Gateway

Related Pages

Related topics: ReviewBot Overview & System Architecture, Development, Extensibility & Operations

Supported Code Checking Tools & Configuration

Overview

Review Bot is an automated code-review worker that wraps a wide range of industry-standard static analysis and linting tools and surfaces their output as Review Board comments. Tools are pluggable Python classes registered through setuptools entry points and executed asynchronously by a Celery-based worker. Configuration is supplied by administrators through Review Board's built-in Integrations UI and passed to each tool at run time via the settings dictionary on the tool instance.

The user-facing list of supported tools is documented in the project README, grouped by language family (C/C++, Go, Java, JavaScript, Python, Ruby, Rust, Shell Scripts). Each tool name in that list maps to a Python entry point declared in bot/setup.py, which is how the worker discovers and loads the class. As noted in the 4.1 release notes, several tools (such as cargo clippy) had to be updated because upstream changes in their output format caused "parsing issues and garbled comments" in earlier versions — keeping the registered class list aligned with current tool behavior is therefore part of normal maintenance.

Tool Architecture: BaseTool and Mixins

Every code-checking tool in Review Bot inherits from BaseTool (defined in bot/reviewbot/tools/base/tool.py), which provides the common lifecycle hooks and class-level metadata. The BaseTool class declares class attributes that subclasses override to describe themselves:

• name — the human-readable name shown in the Integrations UI.
• description — a short summary of what the tool checks.
• version — a compatibility version string; bumping it is treated as a breaking change for existing integrations.
• exe_dependencies — a list of executable names that must be available on PATH for the tool to run (the worker uses is_exe_in_path to verify).
• file_patterns — glob patterns matched against filenames to decide whether a file should be checked.
• options — a list of dictionaries describing the form fields exposed in the integration configuration UI.

To reduce boilerplate, BaseTool is composed with mixins exported from bot/reviewbot/tools/base/__init__.py:

• FilePatternsFromSettingMixin — derives file patterns from user-supplied settings (a comma-separated list of extensions or globs), falling back to the class default. Source: bot/reviewbot/tools/base/mixins.py.
• FullRepositoryToolMixin — used by tools that must analyze the entire repository at once (e.g. Clang).
• JavaToolMixin — supplies JVM execution plumbing for Java-based tools.

The re-exports in bot/reviewbot/tools/__init__.py make BaseTool the canonical import for any plugin author.

classDiagram
    class BaseTool {
      +name: str
      +description: str
      +version: str
      +exe_dependencies: list
      +file_patterns: list
      +options: list
      +handle_file()
    }
    class FilePatternsFromSettingMixin
    class FullRepositoryToolMixin
    class JavaToolMixin
    class JSHintTool
    class ClangTool
    class CheckstyleTool
    BaseTool <|-- JSHintTool
    BaseTool <|-- ClangTool
    BaseTool <|-- CheckstyleTool
    FilePatternsFromSettingMixin <|-- JSHintTool
    FullRepositoryToolMixin <|-- ClangTool
    JavaToolMixin <|-- CheckstyleTool

Configuring Tools

Per-tool options

Each tool's options list is rendered by the Review Bot extension into a Django form. A typical entry, as seen in bot/reviewbot/tools/jshint.py, has the shape:

{
    'name': 'extra_ext_checks',
    'field_type': 'django.forms.CharField',
    'default': '',
    'field_options': {
        'label': 'Extra file extensions',
        'help_text': 'A comma-separated list of extra file extensions to check.',
        'required': False,
    },
}

The same convention is used in bot/reviewbot/tools/clang.py (cmdline_args) and bot/reviewbot/tools/checkstyle.py (a CharField with a Textarea widget for XML configuration). The default and help_text keys flow into the admin form, while field_type and field_options map directly to Django form-field constructors.

File patterns

FilePatternsFromSettingMixin lets administrators add file types without editing source code. For JSHint, the default file_patterns = ['*.js'] is augmented by the user-supplied extra_ext_checks setting, which is parsed into a comma-separated list (using the project's split_comma_separated helper in bot/reviewbot/tools/base/mixins.py). Pattern matching itself is done with fnmatchcase from the standard library, so globs are case-sensitive and Unix-style.

Worker-level settings

Beyond per-tool options, the extension exposes integration-wide settings. The maximum number of comments per review (MAX_COMMENTS_DEFAULT) caps how many diff comments a single run can produce, with a warning surfaced when the cap is exceeded (Source: extension/reviewbotext/forms.py). As of Review Bot 4.1, a new notify_owner_only boolean was added to the configuration form and to the corresponding to_owner_only field on the review-resource WebAPI; when set, e-mail notifications for tool-generated reviews are sent only to the owner of the review request (Source: extension/reviewbotext/resources.py).

Registered Tools

Tools are wired into the worker through the reviewbot.tools entry-point group declared in bot/setup.py. Each line maps a short key to a fully qualified class name. The currently shipped tools include:

Tools that emit CodeClimate-formatted JSON share add_comment_from_codeclimate_issue from bot/reviewbot/tools/utils/codeclimate.py, which converts the location.positions block into a Review Board diff comment with first_line, num_lines, start_column, and error_code populated from the payload. Test scaffolding for new tools lives in bot/reviewbot/tools/testing/testcases.py, which provides a metaclass-driven base class that auto-splits simulation and integration tests.

See Also

• README.rst — full list of supported tools grouped by language.
• Review Bot documentation — installation and configuration guides.
• Review Bot 4.1 release notes — recent tool-format compatibility updates.

Related Pages

Related topics: ReviewBot Overview & System Architecture, Development, Extensibility & Operations

Deployment & Infrastructure

Review Bot is distributed as two cooperating Python packages that together form an automated code review pipeline for Review Board. Understanding how these packages are packaged, installed, and wired together is essential for any deployment.

Package Architecture

Review Bot is split into two independently installable components, each with its own setup.py and PyPI distribution. This separation lets administrators scale the worker independently from the Review Board web service that hosts the extension.

Source: bot/setup.py and extension/setup.py. The README explicitly distinguishes the Review Bot extension and Review Bot worker packages and links to their PyPI pages (README.rst).

Both packages declare python_requires='>=3.8' and advertise support for Python 3.8 through 3.13 in their classifiers (bot/setup.py, extension/setup.py). The license is MIT, and both are classified as Production/Stable.

Runtime Topology

flowchart LR
    RR[Review Request Published] --> EXT[ReviewBotExtension<br/>in Review Board]
    EXT -->|enqueues| WORKER[reviewbot-worker]
    WORKER -->|clones| REPO[Repository Backend]
    WORKER -->|invokes| TOOL[Tool Executables]
    TOOL -->|stdout/stderr| WORKER
    WORKER -->|POST /reviews/| EXT
    EXT -->|notification| OWNER[Review Request Owner]

The extension listens for two Review Board signals: review_request_published and status_update_request_run. It uses SignalHook from Djblets to dispatch them to handler methods on the integration. Source: extension/reviewbotext/integration.py. When a matching review request is published, the extension schedules work; the worker then fetches the diff, checks out the repository, runs configured tools, and posts a review back through the web API.

Installation Surfaces

Because the worker spawns external executables for each tool (for example clang for the Clang tool, cargo and cargo-clippy for the CargoTool, jshint for JSHint), each host running the worker must have the relevant binaries on the PATH or configured via Review Bot's exe_paths setting. Source: bot/reviewbot/tools/clang.py, bot/reviewbot/tools/cargotool.py, bot/reviewbot/tools/jshint.py. Each tool declares its dependencies in an exe_dependencies list and resolves the absolute path via config['exe_paths'][...].

For tools that need the full repository (such as the Clang analyzer and CargoTool), the worker uses a FullRepositoryToolMixin. The repository backend implementation uses appdirs.site_data_dir('reviewbot') to determine where to store per-repository clones, ensuring the data directory follows OS conventions (XDG on Linux, Library/Application Support on macOS, %APPDATA% on Windows). Source: bot/reviewbot/repositories.py.

Configuration and Operational Notes

Operator-facing configuration is exposed through a Django integration form (ReviewBotConfigForm) registered with the extension. The form lets administrators select which tools to run, configure per-tool options (as CharField, BooleanField, and ChoiceField widgets), and set a hard cap on the number of comments a single review may produce. Source: extension/reviewbotext/forms.py. Recent releases have added new options here; for example, Review Bot 4.1 introduced a notify_owner_only toggle that, when enabled, restricts review e-mail notifications to the review request owner rather than all subscribers. Source: extension/reviewbotext/forms.py, extension/reviewbotext/resources.py (where the matching to_owner_only API parameter is declared with added_in: '4.1').

The extension also serves a web API endpoint for creating reviews. The create handler accepts review bodies (body_top, body_bottom), diff comments, general comments, and the new to_owner_only flag, then publishes the review on behalf of the configured bot user. Source: extension/reviewbotext/resources.py.

For tool authors and operators extending the system, the codebase provides a mixin, FilePatternsFromSettingMixin, that lets a tool accept a comma-separated list of additional file extensions or glob patterns at runtime instead of relying solely on the hard-coded file_patterns list. Source: bot/reviewbot/tools/base/mixins.py.

Failure Modes and Compatibility

The community release notes highlight two recurring operational concerns. First, tool output formats change frequently — the 4.1 release notes mention restoring correct parsing for cargo clippy and cargo after upstream output changes produced garbled comments. Second, Review Board major-version compatibility is a moving target; release 3.2 explicitly noted improvements for Review Board 5 and 6. Operators upgrading Review Board should check the Review Bot release notes for the matching compatibility fixes before deploying.

Because the worker relies on per-tool binaries, a deployment should pin tool versions alongside the worker version, and treat any tool upgrade as a potentially breaking change to the review output pipeline.

See Also

• README.rst — project overview and tool index
• bot/README.rst — worker-specific documentation
• extension/reviewbotext/integration.py — signal hooks and integration lifecycle
• extension/reviewbotext/resources.py — review-creation web API

Related Pages

Related topics: ReviewBot Overview & System Architecture, Supported Code Checking Tools & Configuration, Deployment & Infrastructure

Development, Extensibility & Operations

Review Bot is organized as two cooperating Python packages distributed via PyPI: the Review Board extension (reviewbot-extension) that runs inside the Review Board web process, and the standalone worker (reviewbot-worker) that consumes queued jobs and executes code-checking tools. The split keeps the heavy lifting off the web server while letting administrators configure tools through the standard Review Board admin UI (Source: README.rst:1-30, bot/README.rst:1-15, extension/README.rst:1-15).

Two-Package Architecture

The top-level README.rst advertises both halves — reviewbot-extension and reviewbot-worker — as installable components, and each subproject ships its own setup.py declaring an identical supported-Python range (3.8 through 3.13) and a matching MIT-licensed, Review Board-framework classifier profile (Source: bot/setup.py:6-15, extension/setup.py:9-18). The extension side depends on celery~=5.3 to dispatch work, while the worker is a pure consumer of those tasks (Source: extension/setup.py:5-7).

flowchart LR
    A[Review Board Server] -->|runs| B(reviewbot-extension)
    B -->|queues tasks| C[Celery Broker]
    C -->|delivers jobs| D(reviewbot-worker)
    D -->|invokes| E[BaseTool subclass]
    E -->|HTTP API| A

At runtime, the extension installs a ReviewBotIntegration that connects to the review_request_published and status_update_request_run signals (Source: extension/reviewbotext/integration.py:40-55). When a matching event fires, the integration enqueues a job; the worker, connected to the same broker, picks it up, runs the configured tools, and posts the resulting review back through the Review Board Web API (Source: extension/reviewbotext/resources.py:30-60).

Extending Review Bot with New Tools

A new code-checking tool is added by subclassing BaseTool in bot/reviewbot/tools/. The base contract requires four declarative attributes — name, version, description, and a list of exe_dependencies the worker must verify before invocation. ClangTool illustrates the pattern, declaring exe_dependencies = ['clang'] and restricting its work to *.c, *.cc, *.cpp, *.cxx, *.c++, *.m, and *.mm (Source: bot/reviewbot/tools/clang.py:18-35). For tools that need access to a full source tree, the FullRepositoryToolMixin adds cloning logic so the tool can cargo build or rustc against the whole project (Source: bot/reviewbot/tools/cargotool.py:21-30).

User-configurable options are declared as a list of Django-style field descriptors. CargoTool exposes clippy and test toggles built on django.forms.BooleanField (Source: bot/reviewbot/tools/cargotool.py:33-58), while ClangTool adds a free-form cmdline_args text field whose value is read inside build_base_command (Source: bot/reviewbot/tools/clang.py:37-50). Tools that benefit from glob-based file filtering can mix in FilePatternsFromSettingMixin, which lets administrators override extensions and patterns from the admin UI (Source: bot/reviewbot/tools/base/mixins.py:25-50, bot/reviewbot/tools/jshint.py:25-40).

Tools post results back to Review Board by calling comment helpers on a reviewbot.processing.review.File object. Shared utilities such as add_comment_from_codeclimate_issue translate a CodeClimate JSON payload into a positioned diff comment (Source: bot/reviewbot/tools/utils/codeclimate.py:10-25). The BaseCommentData, GeneralCommentData, and DiffCommentData typed dictionaries describe the structure of comment payloads that the extension's Web API endpoint accepts (Source: bot/reviewbot/processing/review.py:25-60).

Testing, Configuration, and Operational Concerns

The worker ships a test harness in bot/reviewbot/tools/testing/testcases.py. ToolTestCaseMetaclass splits any method marked as a simulation or integration test into individual test cases, and asserts that subclasses provide the required tool_class, tool_exe_config_key, and tool_exe_path attributes when the tool declares executable dependencies (Source: bot/reviewbot/tools/testing/testcases.py:20-45). This makes it straightforward to write tests that run the tool against a fake binary without depending on host installations.

On the extension side, ReviewBotConfigForm is the primary operations surface. It exposes tool selection, the max_comments ceiling (with explanatory help text warning about browser performance when set too high), and — new in 4.1 — a notify_owner_only BooleanField that scopes review e-mail notifications to the review request owner (Source: extension/reviewbotext/forms.py:10-30). The matching to_owner_only field on the reviews Web API resource is documented with added_in: '4.1' and is threaded through the create method (Source: extension/reviewbotext/resources.py:35-55). These two changes are the most visible operational improvements in the 4.1 release line and align with the release notes' emphasis on better notification control.

Repository access is abstracted through BaseRepository in bot/reviewbot/repositories.py, which records the Review Board tool_name and a repo_types tuple so SCM-specific backends (Git, Mercurial, etc.) can be plugged in without changing the tool layer (Source: bot/reviewbot/repositories.py:20-50). Finally, extension/reviewbotext/compat/__init__.py is the designated landing spot for compatibility shims that smooth over differences between Review Board 5 and 6, matching the 3.2 release notes' focus on cross-version support (Source: extension/reviewbotext/compat/__init__.py:1-10).

Compatibility and Deployment Matrix

Both packages share the same Python 3.8–3.13 support window and the same Review Board-framework classifier profile, which simplifies rolling upgrades (Source: bot/setup.py:6-15, extension/setup.py:9-18). Operators can install the extension directly from PyPI or pull official Docker images referenced in the top-level README. Community reports around the 4.1 release highlight that several tools — notably cargo clippy and cargo test — have changed their output format in recent versions, so workers upgrading into the 4.x line should expect parser fixes for "garbled comments" regressions to ship with the upgrade. When extending Review Bot, the safe pattern is to keep parsing code in dedicated helpers, gate behavior behind exe_dependencies, and ship a matching test case in the worker's test suite so future tool-version churn is contained.

See Also

• Architecture & Components
• Tool Reference
• Configuration & Deployment
• Review Bot 4.1 Release Notes
• Review Bot 3.2 Release Notes

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