Merge request reviews

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

Merge requests are the primary method of making changes to files in a GitLab project. Create and submit a merge request to propose changes. Your team leaves comments on your merge request, and makes suggestions you can accept from the user interface. When a teammate reviews your work, they can choose to accept or reject it.

To review merge requests, you can use:

For an overview, see Merge request review.

View the review status of a merge request

To do this:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests and find your merge request.
  3. Select the title of the merge request to view it.
  4. Scroll to the merge request widget to see the mergeability and approval status for the merge request. For example, this merge request is blocked because it hasn’t received the approvals it needs:

    The merge request widget displays 'All required approvals must be given'.

To see the individual review status for each reviewer, check the right sidebar of a merge request. Each Reviewer shows the status to the right of the user’s name:

Request a review

To assign a reviewer to a merge request, in a text area in the merge request, use the /assign_reviewer @user quick action, or:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests and find your merge request.
  3. Select the title of the merge request to view it.
  4. On the right sidebar, in the Reviewers section, select Edit.
  5. Search for the user you want to assign, and select the user.

GitLab adds the merge request to the user’s review requests.

From multiple users

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

To assign multiple reviewers to a merge request, in a text area in the merge request, use the /assign_reviewer @user1 @user2 quick action, or:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests and find your merge request.
  3. Select the title of the merge request to view it.
  4. On the right sidebar, in the Reviewers section, select Edit.
  5. From the dropdown list, select all the users you want to assign to the merge request.

To remove a reviewer, clear the user from the same dropdown list.

Re-request a review

After a reviewer completes their merge request reviews, the author of the merge request can request a new review from the reviewer:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests and find your merge request.
  3. Select the title of the merge request to view it.
  4. If you have collapsed the right sidebar in the merge request, select the Expand Sidebar to expand it.
  5. In the Reviewers section, select the Re-request a review icon () next to the reviewer’s name.

GitLab creates a new to-do item for the reviewer, and sends them a notification email.

Start a review

If a user has asked you to review a merge request:

  1. Either:
    • Press Shift + r to go to your Review requests page.
    • On the left sidebar, select Merge requests () > Review requests.
  2. Find your merge request, and select the title of the merge request to view it.
  3. Read the merge request description and comments to learn about the merge request.
  4. Select Changes to view the diff of the proposed changes. To learn more about the Changes page, see Changes in merge requests.
  5. Suggest multi-line or single-line changes as needed. If you select Start a review instead of Add comment now, your review comments remain unpublished until your review is complete.

  6. To add more comments after you’ve selected Start a review, add them to your review from:
    • The Changes tab, containing the diff view.
    • The Overview tab, and selecting Add to review:

    New thread

  7. Select Submit your review to publish all review comments added with either Start a review or Add to review. Until you submit your review, these comments remain unpublished.

Resolve or unresolve thread with a comment

Review comments can also resolve or unresolve resolvable threads. To resolve or unresolve a thread when replying to a comment:

  1. In the comment text area, write your comment.
  2. Select or clear Resolve thread.
  3. Select Add comment now or Add to review.

Pending comments display information about the actions that are delayed until comment is published:

  • Thread is resolved.
  • Thread stays unresolved.

Submit a review

To submit your completed review, you can:

  • Use the /submit_review quick action in the text of a non-review comment.
  • Select Finish review, then select Submit review at the bottom of the dialog. In the dialog, you can supply a Summary comment, approve (or reject) the merge request, and include quick actions:

    Finish review with comment

When you submit your review, GitLab:

  • Publishes the comments in your review.
  • Sends a single email to every notifiable user of the merge request, with your review comments attached. Replying to this email creates a new comment on the merge request.
  • Perform any quick actions you added to your review comments.
  • Optional. Shows whether you have also approved or requested changes:
    • Comment: Leave general feedback without explicit approval.
    • Approve: Leave feedback and approve the changes.
    • Request changes: Block the merge request from merging until the author addresses your feedback.

Prevent merge when you request changes

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
History

A reviewer requesting changes blocks a merge request from merging. When this happens, the merge request reports area shows the message The change requests must be completed or resolved. To unblock the merge request, the reviewer who requested changes should re-review and approve the merge request.

Bypass a request for changes

If the user who requested changes is unable to re-review or provide an approval, another user with permission to merge the merge request can override this check in the merge request reports area by selecting Bypass:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests and find your merge request.
  3. Select the title of the merge request to view it.
  4. On the merge request Overview, scroll to the merge request reports area.
  5. Next to The change requests must be completed or resolved, select Bypass:

    A merge request that is blocked because a user requested changes

  6. The merge reports area shows Merge with caution: Override added. To see which check was bypassed, select Expand merge checks () and find the check that contains a warning () icon. In this example, the author bypassed The change requests must be completed or resolved:

    This merge request contains a bypassed check, and should be merged with caution.

See how reviewers map to approval rules

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

When you create a merge request, you want to request reviews from subject matter experts for the changes you’re making. To decrease the number of review cycles for your merge request, consider requesting reviews from users listed in the project’s approval rules.

When you edit the Reviewers field in a new or existing merge request, GitLab shows you the matching approval rule below the name of each reviewer. Code Owners display as Codeowner without any group detail.

Create or edit a merge request
  1. When you create a new merge request, or edit an existing one, select Reviewers.
  2. Begin entering the name of your desired reviewer. Users who are Code Owners, or match an approval rule, show more information below the username:

    Reviewer approval rules in new/edit form

Reviewing a merge request
  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests.
  3. Select your merge request.
  4. On the right sidebar, next to Reviewers, select Edit.
  5. Begin entering the name of your desired reviewer. Users who are Code Owners, or who match an approval rule, show more information below the username:

    Reviewer approval rules in sidebar

Download merge request changes

As a diff

To download the changes included in a merge request as a diff:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests.
  3. Select your merge request.
  4. In the upper-right corner, select Code > Plain diff.

If you know the URL of the merge request, you can also download the diff from the command line by appending .diff to the URL. This example downloads the diff for merge request 000000:

https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff

To download and apply the diff in a one-line CLI command:

curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff" | git apply

As a patch file

To download the changes included in a merge request as a patch file:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests.
  3. Select your merge request.
  4. In the upper-right corner, select Code > Patches.

If you know the URL of the merge request, you can also download the patch from the command line by appending .patch to the URL. This example downloads the patch file for merge request 000000:

https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.patch

To download and apply the patch in a one-line CLI command using git am:

curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.patch" | git am

Suggested Reviewers

Tier: Ultimate Offering: GitLab.com
History

GitLab uses machine learning to suggest reviewers for your merge request.

To suggest reviewers, GitLab uses:

  • The changes in the merge request
  • The project’s contribution graph

Suggested Reviewers also integrates with Code Owners, profile status, and merge request rules. It helps you make a more informed decision when choosing reviewers who can meet your review criteria.

A list of reviewers.

For more information, see Data usage in Suggested Reviewers.

Enable Suggested Reviewers

Enabling Suggested Reviewers triggers GitLab to create the machine learning model your project uses to generate reviewers. The larger your project, the longer this process can take. Usually, the model is ready to generate suggestions after a few hours.

Prerequisites:

  • You have the Owner or Maintainer role for the project.

To do this:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Merge requests.
  3. Scroll to Suggested reviewers, and select Enable suggested reviewers.
  4. Select Save changes.

After you enable the feature, no action is needed. After the model is ready, recommendations populate the Reviewer dropdown list in the right-hand sidebar of a merge request with new commits.

Associated features

Merge requests are related to these features: