Merge request reviews

The merge request review process ensures that subject matter experts review your proposed changes before they are merged. Reviewers add review comments to merge requests, and suggest changes the author can apply directly from the GitLab UI.

Reviewers can use any of these tools to review a merge request:

• The GitLab interface.
• Visual Studio Code, with the GitLab Workflow extension for VS Code.
• A terminal window, with the GitLab CLI.

Approvals are one of several merge checks that ensure your merge request merges only when it’s truly ready. Depending on your project configuration, reviewers can also block a merge request from merging by setting Request changes.

GitLab Premium and Ultimate provide an Assign reviewers drawer with more information to help you find reviewers who fulfill approval rules:

By following the defined review flow, each reviewer decides whether to accept or reject a merge request. The right sidebar shows the list of reviewers, and (if they follow the review flow) their review status:

• Review not yet started.
• Review is in progress.
• Reviewed and approved.
• Reviewed, requested changes, and blocked this merge request until changes are made. This block can be bypassed.

For an overview, see Merge request review.

Find merge requests to review

Your merge request homepage shows your merge requests in progress, and merge requests awaiting review from you. The merge requests you need to review are in the Review requested category. To see all merge requests that need your attention, use one of these methods:

• Press the Shift + m keyboard shortcut.
• On the left sidebar, select Merge requests ( ).
• On the left sidebar, select Search or go to then, from the dropdown list, select Merge requests I’m working on.

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, the lack of required approvals blocks this merge request:

   

Request a review

When you’ve finished preparing your changes, it’s time to request a review. To assign a reviewer to your merge request, either use the /assign_reviewer @user quick action in any text field, 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. To find a reviewer by name: on the right sidebar, in the Reviewers section, select Edit.
5. To find a reviewer who fulfills an approval rule in GitLab Premium and Ultimate:
   1. On the right sidebar, in the Reviewers section, select Assign to open the Assign reviewers drawer.
   2. For each approval rule, select Edit to find a reviewer who fulfills that approval rule.

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

Find reviewers who fulfill approval rules

GitLab Premium and Ultimate help you more quickly find the best reviewers for your merge request. Use the Assign reviewers drawer to filter lists of reviewers. See the Code Owners for the files changed in your merge request, and the users who satisfy your project’s approval rules.

In this example, the merge request requires 3 Code Owner approvals, but has none so far:

To assign eligible approvers in a merge request:

1. In the Reviewers section, select Assign.
2. To see optional approval rules or Code Owners, select Optional approval rules ( ) to show them.
3. Next to the reviewer type you need, select Edit:
   • Code Owners shows only the Code Owners for that file type.
   • Approval rules shows only users who fulfill that approval rule.
4. Select your desired reviewer. (GitLab Premium and Ultimate enable you to select more than one reviewer.)
5. Repeat for each required Code Owner and Approval rule item.
6. When you’ve selected your reviewers, on the top right, select Close ( ) to hide the Assign reviewers drawer.

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. To do this, either use the /request_review @user quick action in any text field on the merge request, 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. 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

When reviewing a merge request, follow the review process instead of leaving individual comments. When you select Start a review, the Reviewers section of the right sidebar updates your status from Awaiting review ( ) to Reviewer started review ( )

To start your review of 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. When ready to save your first review comment, select Start a review to:

   • Update your status in the right sidebar to Reviewer started review ( ).

   • Save your review comment, but leave it unpublished, like this:

     

   If you select Add comment now instead of Start a review, GitLab publishes your comment immediately.

6. Continue writing review comments on the Changes tab or the Overview tab. Selecting Add to review keeps them unpublished until you submit your review:

   

Next, submit your review.

Resolve or reopen thread with a comment

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

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

Pending comments display information about delayed actions. GitLab does not perform these actions until you publish the comment:

• Resolves thread.
• Thread stays open.

Submit a review

When you submit a review, GitLab does the following:

• 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.
• Performs any quick actions you added to your review comments.
• Shows the outcome of your review.

To submit your completed review:

1. On the top right, select Your review to show details about your review:

   

2. Review your pending comments. Edit them as needed.

3. Select the outcome of your review.

   • Approve: Leave feedback and approve the changes.
   • Comment: Leave general feedback without an explicit approval or change request.
   • Request changes: Block the merge request from merging until the author addresses your feedback.

4. Optional. Write a summary of your review. GitLab Premium and Ultimate users can select Add summary ( ) to create a summary for you. Include any quick actions you want performed.

You can also use the /submit_review quick action in the text of a non-review comment.

Prevent merge when you request changes

A reviewer requesting changes blocks a merge request from merging. When this happens, the merge request reports area shows the message Change requests must be approved by the requesting user. To unblock the merge request, the reviewer who requested changes should re-review and approve the merge request.

Remove a change request

If you previously requested changes, you can remove your change request. You might need to do this if both of the following are true:

• You can no longer approve the merge request.
• You want to cancel your change request, but don’t want to submit a new review.

To remove your change request without submitting a new review:

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 Change requests must be approved by the requesting user, select Remove:

   

Bypass a request for changes

If the user who requested changes is unavailable to re-review or approve, another user with permission to merge the merge request can override this check:

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 Change requests must be approved by the requesting user, select Bypass:

   

6. The merge reports area shows Merge with caution: Override added. To see which check a user bypassed, select Expand merge checks ( ) and find the check that contains a warning ( ) icon. In this example, the author bypassed Change requests must be approved by the requesting user:

   

Download merge request changes

You can download the changes from a merge request as a diff or patch file. For more information and examples, see Download merge request changes.

Associated features

Merge requests are related to these features:

• Cherry-pick changes: In the GitLab UI, select Cherry-pick in a merged merge request or a commit to cherry-pick it.
• Compare changes: View and download the diff of changes included in a merge request.
• Fast-forward merge requests: For a linear Git history and a way to accept merge requests without creating merge commits
• Find the merge request that introduced a change: When viewing the commit details page, GitLab links to the merge requests containing that commit.
• Merge requests versions: Select and compare the different versions of merge request diffs
• Resolve conflicts: GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI.
• Revert changes: Revert changes from any commit from a merge request.
• Keyboard shortcuts: Access and change specific parts of a merge request with keyboard commands.
• Value stream analytics: Track key merge request steps (such as reviewed and approved) to identify where your team spends the most time in the software development lifecycle. This information helps uncover actionable insights to optimize merge request workflows for groups and projects, and improve developer productivity. Read more about How we reduced MR review time with value stream analytics.

Related topics

• Compare changes in merge requests
• Compare branches
• Merge methods
• Draft Notes API