Skip to main content
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:
CheckWebhookManual
Project existsRequiredRequired
Project enabledRequiredRequired
Auto-review toggle onRequiredNot checked
AI config presentRequiredRequired
Platform config completeRequiredRequired
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

Build docs developers (and LLMs) love

Get started for freeTalk to us