Code Review Flow

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Depending on your add-on and group settings, GitLab runs one of two code review features:

  • Code Review Flow: the agentic version, part of GitLab Duo Agent Platform.
  • GitLab Duo Code Review: the non-agentic version, available only for users with the GitLab Duo Enterprise add-on.

This page describes the agentic version.

For more information about how the two features compare and how to turn on Code Review Flow for GitLab Duo Enterprise seats, see use GitLab Duo to review your code.

The Code Review Flow helps you streamline code reviews with agentic AI.

This flow:

  • Analyzes code changes.
  • Provides enhanced contextual understanding of repository structure and cross-file dependencies.
  • Delivers detailed review comments with actionable feedback.
  • Supports custom review instructions tailored to your project.

Prerequisites

Use the flow

The Code Review Flow is available in the GitLab UI and through the REST API.

Code Review Flow runs as a service account, which affects how its usage is billed. For more information, see billing subjects for credit usage.

Request a review in the GitLab UI

To request a review in the GitLab UI:

  1. In the left sidebar, select Code > Merge requests and find your merge request.

  2. Use one of these methods to request a review:

    • Assign @GitLabDuo as a reviewer.
    • In a comment box, enter the quick action /assign_reviewer @GitLabDuo.
    • In a comment box, mention @GitLabDuo and ask for a review.
    • In the GitLab Duo sidebar, open a new or existing Agentic Chat conversation. Ask Agentic Chat to review the merge request.
  3. To monitor progress, in the left sidebar, select AI > Sessions.

    If you are in Agentic Chat, you can also do the following:

    • See the progress in the Chat conversation.
    • Select View Agent Session in the conversation.

Request a review through the REST API

  • Status: Experiment

To request a review through the REST API, trigger the flow with these parameters:

  • Set project_id to the project that contains the merge request.
  • Set goal to either the IID of the merge request to review, or the full URL of that merge request.
  • Set workflow_definition to code_review/v1. Alternatively, set ai_catalog_item_consumer_id to the consumer ID for Code Review Flow.
  • Set start_workflow to true to start the review immediately.

The following example triggers a code review of merge request 42:

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "5",
    "goal": "42",
    "workflow_definition": "code_review/v1",
    "start_workflow": true
  }' \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows"

Interact with GitLab Duo in reviews

After a review, you can discuss the feedback with GitLab Duo in comment interactions. Interactions are a separate feature from Code Review Flow.

For more information, see interact with GitLab Duo.

Approvals and change requests

  • Status: Beta

The availability of this feature is controlled by a feature flag. For more information, see the history.

GitLab Duo can approve or request changes on a merge request based on its review findings:

  • When GitLab Duo finds nothing to comment on, it approves the merge request. An approval from GitLab Duo does not count toward required approvals. If the merge request changes while GitLab Duo reviews the merge request, GitLab Duo does not approve. To get an approval for the latest changes, request a new review.

  • When GitLab Duo finds something to comment on, it requests changes. If a user’s request for changes blocks a merge request on your project, a request from GitLab Duo has the same effect. The request for changes remains until GitLab Duo approves in a follow-up review, or a user bypasses the request for changes.

Provide feedback on this feature in issue 634068.

You can turn on this setting for a project, a group, or an instance.

Prerequisites:

To turn on GitLab Duo approvals and requests for changes for a project:

  1. In the top bar, select Search or go to and find your project.
  2. In the left sidebar, select Settings > Merge requests.
  3. In the GitLab Duo Code Review section, select GitLab Duo can approve and request changes.
  4. Select Save changes.

Prerequisites:

To turn on GitLab Duo approvals and requests for changes for a group:

  1. In the top bar, select Search or go to and find your group.
  2. In the left sidebar, select Settings > General.
  3. Expand the Merge requests section.
  4. In the GitLab Duo Code Review section, select GitLab Duo can approve and request changes.
  5. Select Save changes.

Settings cascade from group to project. More specific settings override broader ones.

Prerequisites:

To turn on GitLab Duo approvals and requests for changes for an instance:

  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select Settings > General.
  3. In the GitLab Duo Code Review section, select GitLab Duo can approve and request changes.
  4. Select Save changes.

Settings cascade from instance to group to project. More specific settings override broader ones.

Follow-up reviews

To start a follow-up review, ask GitLab Duo to review the merge request again. If Start a new review on push is turned on, pushing new changes also starts a follow-up review.

When GitLab Duo re-reviews a merge request, it uses context from its earlier reviews to evaluate the new changes.

Context from earlier reviews

A follow-up review uses this context:

  • Inline comment threads that GitLab Duo started in earlier reviews, including every reply and whether the thread is resolved.
  • The most recent commit that GitLab Duo left inline review comments on.

GitLab Duo reads the whole diff and follows these rules when it comments:

  • It places comments on lines that were added after the last commit it commented on.
  • If no lines were added after that commit, it places comments anywhere in the diff.
  • If it identifies a correctness problem, such as a bug, security vulnerability, or data loss, it places comments anywhere in the diff.
  • It does not repeat points that its earlier threads already make, even if a thread is resolved.

A follow-up review does not use threads that people started, general merge request comments, or the previous summary comment. If there are no previous inline comments from GitLab Duo, the next review is a full first-pass review.

Work with follow-up reviews

GitLab Duo does not reply to or resolve its earlier threads.

To get the most from follow-up reviews:

  • Reply on the thread to explain why the code is correct. GitLab Duo accepts the explanation and does not raise the point again. Without a reply, GitLab Duo lists the finding as outstanding in the review summary, even if the thread is resolved.
  • Push fixes and let GitLab Duo verify them in the next review.
  • Keep discussion of a GitLab Duo finding in its thread. Follow-up reviews do not read comments outside GitLab Duo threads.

Review level

  • Status: Beta

The availability of this feature is controlled by a feature flag. For more information, see the history.

The review level specifies how much context GitLab Duo gathers for a review, such as the diff, surrounding files, project history, and code relationships.

Code Review Flow supports two review levels:

  • Lite: a fast review for routine changes.
  • Standard: a thorough review for complex changes, where GitLab Duo explores more of the codebase as needed. A Standard review usually surfaces more findings, but takes longer.

Each level has its own model setting and supported models.

Lite reviews use flat pricing, and Standard reviews use variable pricing. For more information, see billing methods.

By default, Code Review Flow runs Lite reviews. To use Standard reviews, turn on experiment and beta features. You can then request a Standard review for a single merge request, or make Standard the default review level for all merge requests.

Change the level for a single review

After GitLab Duo reviews a merge request, you can request another review at a different level.

Prerequisites:

  • Experiment and beta features turned on.
  • Allow Standard reviews turned on for the project. It is on by default.

To change the level for a single review:

  1. In the left sidebar, select Code > Merge requests and find your merge request.
  2. In the right sidebar, under Reviewer, find @GitLabDuo and select Re-request review ( redo ).
  3. Select Lite or Standard.

You can also set the level with the /request_review quick action. In a comment, enter /request_review @GitLabDuo -lite or /request_review @GitLabDuo -standard.

Configure review level settings

You can configure review level settings in a project, a group, or an instance.

When you change a setting for an instance or a group, GitLab applies the new value to all groups, subgroups, and projects below it and replaces their values. You can then change the setting again for a subgroup or a project.

Prerequisites:

To configure the review level for a project:

  1. In the top bar, select Search or go to and find your project.
  2. In the left sidebar, select Settings > Merge requests.
  3. In the GitLab Duo Code Review section:
    • Select or clear the Allow Standard reviews checkbox.
    • Under Review level, select Lite (Default) or Standard.
  4. Select Save changes.

Prerequisites:

To configure the review level for a group and its subgroups and projects:

  1. In the top bar, select Search or go to and find your group.
  2. In the left sidebar, select Settings > General.
  3. Expand the Merge requests section.
  4. In the GitLab Duo Code Review section:
    • Select or clear the Allow Standard reviews checkbox.
    • Under Review level, select Lite (Default) or Standard.
  5. Select Save changes.

Prerequisites:

To configure the review level for all groups and projects in an instance:

  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select Settings > General.
  3. In the GitLab Duo Code Review section:
    • Select or clear the Allow Standard reviews checkbox.
    • Under Review level, select Lite (Default) or Standard.
  4. Select Save changes.

Contextual awareness

Lite and Standard reviews gather context differently:

  • Lite reviews gather all context before the review starts. A pre-scan selects related files from the merge request diffs, and the review uses only those files.
  • Standard reviews start with less context, mostly the merge request diffs. During the review, GitLab Duo fetches more context as needed. This context can include other project files, commit history, and code in other projects that GitLab Duo can access.

To specify content to exclude, see manage context exclusions.

Context for Lite reviews

For Lite reviews, Code Review Flow runs in two stages:

  1. Pre-scan: The flow inspects the merge request diffs and uses them to identify related context to fetch from the project repository. The pre-scan typically includes directory listings and the contents of related files, such as tests and dependencies referenced by the changes. The exact context fetched depends on the diff analysis.

  2. Review: The flow runs the review with the following data in the large language model. The review stage cannot fetch additional context on demand.

    • Results from the pre-scan step.
    • Merge request title.
    • Merge request description.
    • Merge request diffs.
    • Original versions of the files.
    • Filenames.
    • On follow-up reviews, comment threads from previous GitLab Duo reviews, including replies.
    • Custom review instructions.

Context for Standard reviews

For Standard reviews, Code Review Flow starts the review with the following data:

  • Merge request title.
  • Merge request description.
  • Merge request diffs.
  • Filenames.
  • Custom review instructions.
  • On follow-up reviews, comment threads from previous GitLab Duo reviews, including replies.

During the review, GitLab Duo fetches more context when needed. For example, GitLab Duo can:

  • Read other files from the project repository, not only the files the merge request changes.
  • Search the repository for code that uses the changed code.
  • Check the commit history of the changed files.
  • Read files and search code in other projects that GitLab Duo can access, when the change depends on them.

File and context limits

Code Review Flow applies two limits to keep the prompt within a workable size:

  • For a Lite review, files longer than 10,000 lines are sent to the model as diffs only. The full file contents are not included. A Standard review reads long files in parts, so this limit does not apply.
  • The merge request data that the flow fetches at the start of a review is capped at approximately 1 MiB. When the cap is exceeded, the data is truncated to approximately 800 KiB before the review runs. For a Standard review, the review summary states when the review does not cover all of the diff.

These limits apply to the data the flow gathers and are separate from the selected model’s context window.

For very large merge requests, the review might miss context that was truncated. To reduce the risk:

Custom code review instructions

Customize the behavior of Code Review Flow with an mr-review-instructions.yaml file.

You can guide GitLab Duo with repository-specific review instructions:

  • Focus on specific code quality aspects (such as security, performance, and maintainability).
  • Enforce coding standards and best practices unique to your project.
  • Target specific file patterns with tailored review criteria.
  • Provide more detailed explanations for certain types of changes.

Code Review Flow does not reference AGENTS.md and SKILL.md files.

To configure custom instructions, see customize review instructions for GitLab Duo.

Automatic reviews

The availability of this feature is controlled by a feature flag. For more information, see the history.

Automatic reviews from GitLab Duo ensure that all merge requests in your project or group receive an initial review.

When a user creates a merge request, GitLab Duo automatically reviews it unless:

  • It’s marked as draft. For GitLab Duo to review the merge request, mark it ready.
  • It contains no changes. For GitLab Duo to review the merge request, add changes to it.
  • It matches one or more exclusion rules you set. For GitLab Duo to review the merge request, manually request a review.

Automatic reviews are turned on by default for groups:

  • With new GitLab Duo trials on GitLab.com in GitLab 19.1 and later.
  • That add their first GitLab Duo add-on, including those with new Premium and Ultimate subscriptions, on GitLab.com in GitLab 19.5 and later.

Prerequisites:

  • The Maintainer or Owner role for the project.

To turn on automatic reviews for a project:

  1. In the top bar, select Search or go to and find your project.
  2. In the left sidebar, select Settings > Merge requests.
  3. In the GitLab Duo Code Review section, select Enable automatic reviews by GitLab Duo.
  4. Select Save changes.

Prerequisites:

  • The Owner role for the group.

To turn on automatic reviews for a group:

  1. In the top bar, select Search or go to and find your group.
  2. In the left sidebar, select Settings > General.
  3. Expand the Merge requests section.
  4. In the GitLab Duo Code Review section, select Enable automatic reviews by GitLab Duo.
  5. Select Save changes.

Settings cascade from group to project. More specific settings override broader ones.

After you enable automatic reviews, you can specify rules to exclude specific merge requests.

Start a new review on push

When a user pushes to the source branch of a merge request, GitLab Duo starts a follow-up review if all of the following are true:

  • Automatic reviews are turned on for the project.
  • Code Review Flow, not GitLab Duo Code Review, runs for the merge request author.
  • The merge request is open and not a draft.
  • GitLab Duo is already a reviewer on the merge request.
  • The push changes the diff.

A push that does not change the diff, such as a rebase with no content change, does not start a new review. If a GitLab Duo review is in progress when the push occurs, GitLab stops that review and starts a new one.

Start a new review on push is turned on by default. You can turn it off for a project or group.

Prerequisites:

  • The Maintainer or Owner role for the project.
  • Automatic reviews are turned on.

To change this setting for a project:

  1. In the top bar, select Search or go to and find your project.
  2. In the left sidebar, select Settings > Merge requests.
  3. In the GitLab Duo Code Review section, select or clear Start a new review on push.
  4. Select Save changes.

Prerequisites:

  • The Owner role for the group.
  • Automatic reviews are turned on.

To change this setting for a group:

  1. In the top bar, select Search or go to and find your group.
  2. In the left sidebar, select Settings > General.
  3. Expand the Merge requests section.
  4. In the GitLab Duo Code Review section, select or clear Start a new review on push.
  5. Select Save changes.

Settings cascade from group to project. More specific settings override broader ones.

Exclude merge requests for a project

When automatic reviews are turned on for a project, GitLab Duo reviews every eligible merge request. To exclude specific merge requests, define exclusion rules in a .gitlab/duo/mr-review-automated-rules.yaml file.

Exclusion rules only prevent automatic reviews. You can still request a review manually for any excluded merge request.

To define exclusion rules:

  1. In the root of your repository, create a .gitlab/duo directory if one doesn’t already exist.

  2. In the .gitlab/duo directory, create a file named mr-review-automated-rules.yaml.

  3. Add exclusion rules using the following format:

    yaml
    exclude:
      target_branches:
        - <pattern>
      source_branches:
        - <pattern>
      authors:
        - <pattern>

    Each key is optional. GitLab Duo skips the automatic review when a merge request matches any pattern in any category:

    • target_branches: Matches the target branch name of the merge request.
    • source_branches: Matches the source branch name of the merge request.
    • authors: Matches the username of the merge request author.

    Patterns support wildcard (glob) matching. For example, dependabot/* matches any source branch that starts with dependabot/.

    For example, to skip automatic reviews for merge requests that target a release branch or that a bot account creates:

    yaml
    exclude:
      target_branches:
        - "release/*"
      authors:
        - "*-bot"
  4. Commit the file to the default branch of your repository.

GitLab Duo reads the exclusion rules from the default branch of your repository. GitLab Duo does not apply rules on other branches.

Exclude merge requests for a group

To define exclusion rules for all projects in a group and its subgroups, specify a project to use as a template. The template project must contain a .gitlab/duo/mr-review-automated-rules.yaml file.

GitLab Duo combines the exclusion rules from the group template project with the rules defined in the individual project. If the same category is defined at both levels, the project’s rules take precedence. When a group and its subgroups each set a template project, GitLab Duo combines the rules from every level.

If you already configured a project to store custom review instructions for your group, store your mr-review-automated-rules.yaml in the same project. You can only specify a single project to customize code review for a group, so GitLab automatically checks that project for exclusion rules as well. You do not need to follow the steps below again.

Prerequisites:

  • The Owner role for the group.
  • A project in the group contains the exclusion rules that you want to set.

To configure exclusion rules for a group:

For a top-level group:

  1. In the top bar, select Search or go to and find your top-level group.
  2. In the left sidebar, select Settings > GitLab Duo.
  3. Select Change configuration.
  4. Under GitLab Duo features > Customize code review, select the project that contains the .gitlab/duo/mr-review-automated-rules.yaml file.
  5. Select Save changes.

For a group or subgroup:

  1. In the top bar, select Search or go to and find your group or subgroup.
  2. In the left sidebar, select Settings > General.
  3. Expand GitLab Duo features.
  4. Under Customize code review, select the project that contains the .gitlab/duo/mr-review-automated-rules.yaml file.
  5. Select Save changes.
  1. In the top bar, select Search or go to and find your group or subgroup.
  2. In the left sidebar, select Settings > General.
  3. Expand GitLab Duo features.
  4. Under Customize code review, select the project that contains the .gitlab/duo/mr-review-automated-rules.yaml file.
  5. Select Save changes.

Troubleshooting

When working with Code Review Flow, you might encounter issues.

For information on how to resolve these issues, see troubleshooting.