Skip to content
Runbooks

Duo Code Review Runbook

Overview

Section titled “Overview”

This page explains how to investigate Duo Code Review issues on production.

Dashboard

Section titled “Dashboard”

Summary

Section titled “Summary”

Duo Code Review is an AI-powered feature that provides automated code review capabilities for merge requests. It helps ensure consistent code review standards and provides intelligent feedback on code changes using LLMs.

It can be enabled by default so that GitLabDuo automatically reviews merge requests, or it can be added manually as a reviewer for on-demand reviews when needed.

Key Features:

  • Automatic reviews of merge requests by @GitLabDuo
  • Interactive code review discussions
  • Custom review instructions per project
  • Integration with GitLab’s merge request workflow

Architecture

Section titled “Architecture”

Duo Code Review follows a similar architecture to other GitLab Duo features:

  1. Frontend: Vue.js components in merge request interface
  2. Backend: Rails GraphQL API and services
  3. AI Gateway: Processes prompts and communicates with LLMs
  4. LLM Integration: Claude/other models for code analysis and review response

For a high-level diagram of the basic internal flow in Rails, refer to this diagram

Prerequisites & Access Control

Section titled “Prerequisites & Access Control”

Licensing Requirements:

  • Tier: Premium, Ultimate
  • Add-on: GitLab Duo Enterprise

Permissions:

  • Maintainer role required to enable automatic reviews
  • Developer role required to interact with @GitLabDuo in merge requests

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”
ProblemSolution
@GitLabDuo not reviewing MREnsure MR is not in the draft state
@GitLabDuo not appearing in the reviewers tabCheck licensing and permissions
Custom instructions not workingVerify .gitlab/duo/mr-review-instructions.yaml format
Reviews taking too longCheck AI Gateway connectivity as well as LLMs’ status
Duo Code Review not available on self-managedVerify the GitLab instance is running minimum version 17.10 or higher and check if the @GitLabDuo user exists on the instance

Monitoring & Observability

Section titled “Monitoring & Observability”

Logs to Monitor

Section titled “Logs to Monitor”
  • llm.log - AI request debugging
  • sidekiq_json.log - Background job processing
  • graphql_json.log - GraphQL API requests

Production Considerations

Section titled “Production Considerations”

Performance

Section titled “Performance”
  • Reviews are processed asynchronously via Sidekiq
  • Large merge requests may take longer to review

Feature Flags

Section titled “Feature Flags”

Current feature flags:

  • cascading_auto_duo_code_review_settings - Group/application level settings (Beta)

Support & Escalation

Section titled “Support & Escalation”

Before escalating

NOTE: Do NOT expose customer’s RED data in public issues. Redact them or make a confidential issue if you’re unsure.

Before starting the investigation and escalating, please collect the following information:

  • User name who encountered the bug (e.g. @janedoe)
  • Type of instance the user is on (e.g. SaaS, self-managed)
  • What happened (e.g. User requested for a review from @GitLabDuo and saw an error code A3010)
  • When it happened (e.g. Around 2025/09/07 01:00 UTC)
  • Where it happened (e.g. MR discussion, review panel)
  • How often the issue occurs (e.g. It happens everytime)
  • Steps to reproduce (e.g. 1. Ask a follow question to review “xxx” 2. Click …)
  • A link to a Slack discussion, if any.

and create an issue in the GitLab Issue tracker and ping @gitlab-org/code-creation/engineers

Internal Support

Section titled “Internal Support”
  • Primary Team: Code Creation
  • Slack Channel: #g_code_creation
  • On-call: Follow standard GitLab on-call procedures

User Support

Section titled “User Support”