Review flow

End-to-end walkthrough of how a code review moves from webhook to results.

Every automated review follows the same execution chain, whether triggered by a platform webhook or started manually. This page traces that chain from start to finish.

Execution chain

┌─────────────────────────────────────────────┐
│  GitLab / GitHub webhook  OR  manual trigger │
└──────────────────────┬──────────────────────┘
                       │
                       ▼
            POST /api/webhook/gitlab
            POST /api/webhook/github
                       │
                       ▼
            ReviewOrchestrator
          (project validation checks)
                       │
                       ▼
     reviewTasks + runnerTasks created
           in BullMQ queue (Redis)
                       │
                       ▼
       Runner polls for tasks via HTTP
                       │
                       ▼
    Review executed in Docker container
                       │
                       ▼
      Runner reports results to server
                       │
                       ▼
   Server stores history, comments,
   file annotations, ratings, feedback
                       │
                       ▼
   Notifications + platform push-back

Step-by-step

1. Webhook arrives

   The platform (GitLab or GitHub) sends an HTTP POST to the server when a merge request or pull request event fires:

   POST /api/webhook/gitlab
   POST /api/webhook/github
   

   The webhook module validates the request signature before passing it to the orchestrator.

2. ReviewOrchestrator validates the project

   modules/reviews/review-orchestrator.service.ts runs a series of checks before any queue work is created. All of the following must pass:

   • Project exists — the repository is known to the system
   • Project is enabled — the project has not been disabled
   • Auto-review is on — the project’s auto-review toggle is active (webhook path only)
   • AI config is available — an AI configuration is attached to the project
   • Platform config is complete — the platform integration (GitLab/GitHub) is fully configured

   If any check fails, the review is rejected early and no tasks are queued.

   Manual triggers bypass the auto-review toggle check but still require the project to exist, be enabled, and have both AI and platform configs present.

3. Tasks are created in the queue

   Once validation passes, the orchestrator creates two linked entries in BullMQ:

   • reviewTasks — tracks the overall review lifecycle
   • runnerTasks — the unit of work a runner will pick up

   Both entries are stored in Redis and are immediately available for polling.

4. Runner picks up the task

   A registered runner polls the server over HTTP at a configurable interval (RUNNER_POLL_INTERVAL_MS). When a task is available, the runner claims it and transitions it from pending to in-progress.

   See Runner for details on registration and polling.

5. Review executes in an isolated container

   The runner uses its Docker executor to spin up an isolated container (configured by DOCKER_EXECUTOR_IMAGE) and runs the full review pipeline inside it:

   • Clone the repository at the target revision
   • Apply the review rules and template
   • Call the configured AI model
   • Collect file-level annotations and an overall assessment

   The following services coordinate this step:

   review-core.service.ts
   review-context.builder.ts
   review-execution.engine.ts
   
6. Runner reports results

   After execution completes (or fails), the runner posts the results back to the server. The server’s review-result.handler.ts processes the payload and persists:

   • Review history record
   • File-level comments and annotations
   • Per-round details
   • Quality ratings
   • Feedback entries
7. Notifications and platform push-back

   With results stored, the server triggers downstream actions:

   • Notifications — configured channels (Slack, email, webhook) receive a summary
   • Platform push-back — comments or review status are posted back to the GitLab MR or GitHub PR

Manual trigger flow

Reviews can also be started manually from the dashboard without a webhook event. The flow is identical from step 2 onward, with one difference: the auto-review toggle check is skipped.

Dashboard → POST /api/reviews  →  ReviewOrchestrator  →  queue  →  runner  →  results

Projectability checks

The table below summarises all conditions the orchestrator verifies before queuing work:

Check	Webhook	Manual
Project exists	Required	Required
Project enabled	Required	Required
Auto-review toggle on	Required	Not checked
AI config present	Required	Required
Platform config complete	Required	Required

If a runner is registered but offline (heartbeat timed out), tasks will accumulate in the queue in a pending state. Reviews will not execute until a healthy runner comes online.

Core service files

The review pipeline is implemented across these files in apps/server/src/modules/reviews/:

review-orchestrator.service.ts  # Entry point, validation, task creation
review-core.service.ts          # Core review logic
review-context.builder.ts       # Assembles context passed to the AI
review-execution.engine.ts      # Drives the AI call and result collection
review-result.handler.ts        # Persists results and triggers downstream