• Bulk edit merge requests at the project level
• Bulk edit merge requests at the group level
• Review a merge request
  • Submit a review
  • Resolving/Unresolving threads
  • Adding a new comment
  • Approval Rule information for Reviewers
  • Requesting a new review
    • Approval status
• Semi-linear history merge requests
• Perform inline code reviews
  • Comment on multiple lines
• Associated features
• Troubleshooting
  • Merge request cannot retrieve the pipeline status
    • Sidekiq
    • Bug
• Tips
  • Copy the branch name for local checkout
  • Checkout merge requests locally through the head ref
    • Checkout locally by adding a Git alias
    • Checkout locally by modifying .git/config for a given repository
• Cached merge request count

Review and manage merge requests

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, 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.

Bulk edit merge requests at the project level

Users with permission level of Developer or higher 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:

1. In a project, go to Merge requests.
2. Click Edit merge requests. A sidebar on the right-hand side of your screen appears with editable fields.
3. Select the checkboxes next to each merge request you want to edit.
4. Select the appropriate fields and their values from the sidebar.
5. Click Update all.

Bulk edit merge requests at the group level

Users with permission level of Developer or higher 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:

1. In a group, go to Merge requests.
2. Click Edit merge requests. A sidebar on the right-hand side of your screen appears with editable fields.
3. Select the checkboxes next to each merge request you want to edit.
4. Select the appropriate fields and their values from the sidebar.
5. Click Update all.

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:

1. Go to the merge request you want to review, and select the Changes tab. To learn more about navigating the diffs displayed in this tab, read Changes tab in merge requests.
2. Select a line of code. In GitLab version 13.2 and later, you can highlight a set of lines.
3. Write your first comment, and select Start a review below your comment:
4. Continue adding comments to lines of code, and select the appropriate button after you write a comment:
   • Add to review: Keep this comment private and add to the current review. These review comments are marked Pending and are visible only to you.
   • Add comment now: Submits the specific comment as a regular comment instead of as part of the review.
5. (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.
6. When your review is complete, you can submit the review. Your comments are now visible, and any quick actions included your comments are performed.

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.
• When creating a review comment, select Submit review.
• Scroll to the bottom of the screen and select Submit review.

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.

Resolving/Unresolving threads

Review comments can also resolve or unresolve resolvable threads. When replying to a comment, a checkbox is displayed to resolve or unresolve the thread after publication.

If a particular pending comment resolves or unresolves the thread, this is shown on the pending comment itself.

Adding a new comment

If you have a review in progress, you will be presented with the option to Add to review:

Approval Rule information for Reviewers

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 suggested 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:

Requesting 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:

1. If the right sidebar in the merge request is collapsed, click the Expand Sidebar icon to expand it.
2. In the Reviewers section, click 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.

Approval status

If a user in the reviewer list has approved the merge request, a green tick symbol is shown to the right of their name.

Semi-linear history merge requests

A merge commit is created for every merge, but the branch is only merged if a fast-forward merge is possible. This ensures that if the merge request build succeeded, the target branch build also succeeds after the merge.

1. Go to your project and select Settings > General.
2. Expand Merge requests.
3. In the Merge method section, select Merge commit with semi-linear history.
4. Select Save changes.

Perform inline code reviews

In a merge request, you can leave comments in any part of the file being changed. In the merge request Diff UI, you can:

• Comment on a single line: Select the comment icon in the gutter to expand the diff lines and display a comment box.
• Comment on multiple lines.

Comment on multiple lines

When commenting on a diff, you can select which lines of code your comment refers to by either:

• Dragging the comment icon 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 the comment icon 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:

Associated features

These features are associated with merge requests:

• Bulk editing merge requests: Update the attributes of multiple merge requests simultaneously.
• 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 request(s) 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.

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. Please wait a few seconds and the status should update automatically.

Bug

Merge request pipeline statuses can’t be retrieved when the following occurs:

1. A merge request is created
2. The merge request is closed
3. Changes are made in the project
4. 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 checkout the branch locally from the command line by running git checkout <branch-name>.

Checkout merge requests locally through the head ref

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.

Introduced in GitLab 13.4, 14 days after a merge request gets closed or merged, the merge request head ref is deleted. This means that the merge request isn’t 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.