Merge request reviews All tiers All offerings
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 Code Suggestions you can accept from the user interface. When your work is reviewed, your team members can choose to accept or reject it.
You can review merge requests from the GitLab interface. If you install the GitLab Workflow VS Code extension, you can also review merge requests in Visual Studio Code.
For an overview, see Merge request review.
GitLab Duo Suggested Reviewers Ultimate SaaS
-
Introduced in GitLab 15.4 as a Beta feature with a flag named
suggested_reviewers_control
. Disabled by default. - Enabled on GitLab.com in GitLab 15.6.
- Beta designation removed from the UI in GitLab 15.10.
- Feature flag removed in GitLab 16.6.
GitLab uses machine learning to suggest reviewers for your merge request.
For an overview, see GitLab Duo Suggested Reviewers.
To suggest reviewers, GitLab uses:
- The changes in the merge request
- The project’s contribution graph
GitLab Duo Suggested Reviewers also integrates with Code Owners, profile status, and merge request rules, helping you make a more informed decision when choosing reviewers that can meet your review criteria.
For more information, see Data usage in GitLab Duo Suggested Reviewers.
Enable Suggested Reviewers
Project Maintainers or Owners can enable Suggested Reviewers by visiting the project settings.
Enabling Suggested Reviewers triggers GitLab to create an ML model for your project that is used to generate reviewers. The larger your project, the longer this process can take. Usually, the model is ready to generate suggestions within a few hours.
No action is required after the feature is enabled. After the model is ready, recommendations populate the Reviewer dropdown list in the right-hand sidebar of a merge request with new commits.
Review a merge request
When you review a merge request, you can create comments that are visible only to you. When you’re ready, you can publish them together in a single action. To start your review:
- Go to the merge request you want to review, and select the Changes tab. For more information about navigating the diffs displayed in this tab, see Changes in merge requests.
- Select Add a comment to this line () in the gutter to expand the diff lines and display a comment box. In GitLab version 13.2 and later, you can select multiple lines.
- In the text area, write your first comment, then select Start a review below your comment.
- Continue adding comments to lines of code. After each comment, select Add to review. Comments made as part of a review are visible only to you until you submit your review.
- Optional. You can use quick actions inside review comments. The comment shows the actions to perform after publication, but does not perform them until you submit your review.
- When your review is complete, you can submit the review. Your comments are now visible, and any quick actions included in your comments are performed.
If you approve a merge request and are shown in the reviewer list, a green check mark displays next to your 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. Alternatively:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests and find your merge request.
- On the right sidebar, in the Reviewers section, select Edit.
- Search for the user you want to assign, and select the user.
The merge request is added to the user’s review requests.
From multiple users Premium All offerings
Moved to GitLab Premium in 13.9.
To assign multiple reviewers to a merge request, in a text area in
the merge request, use the /assign_reviewer @user
quick action. Alternatively:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests and find your merge request.
- On the right sidebar, in the Reviewers section, select Edit.
- 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.
Download merge request changes as a diff
To download the changes included in a merge request as a diff:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests.
- Select your merge request.
- 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
Download merge request changes as a patch file
To download the changes included in a merge request as a patch file:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests.
- Select your merge request.
- 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
Submit a review
You can submit your completed review in multiple ways:
- 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 modal window. In the modal window, you can supply a Summary comment, approve the merge request, and include quick actions:
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. Approves the merge request.
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:
- In the comment text area, write your comment.
- Select or clear Resolve thread.
- Select Add comment now or Add to review.
Pending comments display information about the action to be taken when the comment is published:
- Thread is resolved.
- Thread stays unresolved.
Add a new comment
If you have a review in progress, you can also add a comment from the Overview tab by selecting Add to review:
Approval Rule information for Reviewers Premium All offerings
When editing the Reviewers field in a new or existing merge request, GitLab
displays the name of the matching approval rule
below the name of each reviewer. Code Owners are displayed as Codeowner
without group detail.
This example shows reviewers and approval rules when creating a new merge request:
This example shows reviewers and approval rules in a merge request sidebar:
Request a new review
After a reviewer completes their merge request reviews, the author of the merge request can request a new review from the reviewer:
- If the right sidebar in the merge request is collapsed, select the Expand Sidebar icon to expand it.
- 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.
Comment on multiple lines
When commenting on a diff, you can select which lines of code your comment refers to by either:
- Dragging Add a comment to this line () in the gutter to highlight lines in the diff. GitLab expands the diff lines and displays a comment box.
- After starting a comment by selecting Add a comment to this line () in the gutter, select the first line number your comment refers to in the Commenting on lines select box. New comments default to single-line comments, unless you select a different starting line.
Multiline comments display the comment’s line numbers above the body of the comment:
Bulk edit merge requests at the project level
Users with at least the Developer role can manage merge requests.
When bulk-editing merge requests in a project, you can edit the following attributes:
- Status (open/closed)
- Assignee
- Milestone
- Labels
- Subscriptions
To update multiple project merge requests at the same time:
- In a project, go to Code > Merge requests.
- Select Bulk edit. A sidebar on the right-hand side of your screen appears with editable fields.
- Select the checkboxes next to each merge request you want to edit.
- Select the appropriate fields and their values from the sidebar.
- Select Update all.
Bulk edit merge requests at the group level Premium All offerings
Users with at least the Developer role can manage merge requests.
When bulk editing merge requests in a group, you can edit the following attributes:
- Milestone
- Labels
To update multiple group merge requests at the same time:
- In a group, go to Code > Merge requests.
- Select Bulk edit. A sidebar on the right-hand side of your screen appears with editable fields.
- Select the checkboxes next to each merge request you want to edit.
- Select the appropriate fields and their values from the sidebar.
- Select Update all.
Associated features
These features are associated with merge requests:
- Cherry-pick changes: Cherry-pick any commit in the UI by selecting the Cherry-pick button in a merged merge requests or a commit.
- 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 modify specific parts of a merge request with keyboard commands.
Troubleshooting
Sometimes things don’t go as expected in a merge request. Here are some troubleshooting steps.
Merge request cannot retrieve the pipeline status
This can occur if Sidekiq doesn’t pick up the changes fast enough.
Sidekiq
Sidekiq didn’t process the CI state change fast enough. Wait a few seconds and the status should update automatically.
Bug
Merge request pipeline statuses can’t be retrieved when the following occurs:
- A merge request is created
- The merge request is closed
- Changes are made in the project
- The merge request is reopened
To enable the pipeline status to be properly retrieved, close and reopen the merge request again.
Tips
Here are some tips to help you be more efficient with merge requests in the command line.
Copy the branch name for local checkout
The merge request sidebar contains the branch reference for the source branch used to contribute changes for this merge request.
To copy the branch reference into your clipboard, select the Copy branch name button
() in the right sidebar. Use it to check out the branch locally
from the command line by running git checkout <branch-name>
.
Checkout merge requests locally through the head
ref
- Deleting
head
refs 14 days after a merge request closes or merges enabled on self-managed and GitLab.com in GitLab 16.4. - Deleting
head
refs 14 days after a merge request closes or merges generally available in GitLab 16.6. Feature flagmerge_request_refs_cleanup
removed.
A merge request contains all the history from a repository, plus the additional commits added to the branch associated with the merge request. Here’s a few ways to check out a merge request locally.
You can check out a merge request locally even if the source project is a fork (even a private fork) of the target project.
This relies on the merge request head
ref (refs/merge-requests/:iid/head
)
that is available for each merge request. It allows checking out a merge
request by using its ID instead of its branch.
In GitLab 16.6 and later, the merge request head
ref is deleted 14 days after
a merge request is closed or merged. The merge request is then no longer available
for local checkout from the merge request head
ref anymore. The merge request
can still be re-opened. If the merge request’s branch
exists, you can still check out the branch, as it isn’t affected.
Checkout locally by adding a Git alias
Add the following alias to your ~/.gitconfig
:
[alias]
mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
Now you can check out a particular merge request from any repository and any
remote. For example, to check out the merge request with ID 5 as shown in GitLab
from the origin
remote, do:
git mr origin 5
This fetches the merge request into a local mr-origin-5
branch and check
it out.
Checkout locally by modifying .git/config
for a given repository
Locate the section for your GitLab remote in the .git/config
file. It looks
like this:
[remote "origin"]
url = https://gitlab.com/gitlab-org/gitlab-foss.git
fetch = +refs/heads/*:refs/remotes/origin/*
You can open the file with:
git config -e
Now add the following line to the above section:
fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
In the end, it should look like this:
[remote "origin"]
url = https://gitlab.com/gitlab-org/gitlab-foss.git
fetch = +refs/heads/*:refs/remotes/origin/*
fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
Now you can fetch all the merge requests:
git fetch origin
...
From https://gitlab.com/gitlab-org/gitlab-foss.git
* [new ref] refs/merge-requests/1/head -> origin/merge-requests/1
* [new ref] refs/merge-requests/2/head -> origin/merge-requests/2
...
And to check out a particular merge request:
git checkout origin/merge-requests/1
All the above can be done with the git-mr
script.
Cached merge request count
In a group, the sidebar displays the total count of open merge requests. This value is cached if it’s greater than than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours.