Merge requests

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

A merge request (MR) is a proposal to incorporate changes from a source branch to a target branch.

When you open a merge request, you can visualize and collaborate on the changes before merge. Merge requests include:

  • A description of the request.
  • Code changes and inline code reviews.
  • Information about CI/CD pipelines.
  • A comment section for discussion threads.
  • The list of commits.

Create a merge request

Learn the various ways to create a merge request.

Use merge request templates

When you create a merge request, GitLab checks for the existence of a description template to add data to your merge request. GitLab checks these locations in order from 1 to 5, and applies the first template found to your merge request:

Name Project UI
setting
Group
default.md
Instance
default.md
Project
default.md
No template
Standard commit message 1 2 3 4 5
Commit message with an issue closing pattern like Closes #1234 1 2 3 4 5 *
Branch name prefixed with an issue ID, like 1234-example 1 * 2 * 3 * 4 * 5 *
note
Items marked with an asterisk (*) also append an issue closing pattern.

View merge requests

You can view merge requests for your project, group, or yourself.

For a project

To view all merge requests for a project:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests.

Or, to use a keyboard shortcut, press g + m.

For all projects in a group

To view merge requests for all projects in a group:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Code > Merge requests.

If your group contains subgroups, this view also displays merge requests from the subgroup projects.

Assigned to you

To view all merge requests assigned to you:

  1. On the left sidebar, select Search or go to.
  2. From the dropdown list, select Merge requests assigned to me.

or:

or:

  1. On the left sidebar, select Code > Merge requests ( ).
  2. From the dropdown list, select Assigned.

Filter the list of merge requests

History
  • Filtering by source-branch introduced in GitLab 16.6.
  • Filtering by merged-by introduced in GitLab 16.9. Available only when the feature flag mr_merge_user_filter is enabled.

To filter the list of merge requests:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests.
  3. Above the list of merge requests, select Search or filter results.
  4. From the dropdown list, select the attribute you wish to filter by. Some examples:
    • By environment or deployment date.
    • ID: Enter filter #30 to return only merge request 30.
    • User filters: Type (or select from the dropdown list) any of these filters to display a list of users:
      • Approved-By, for merge requests already approved by a user. Premium and Ultimate only.
      • Approver, for merge requests that this user is eligible to approve. (For more information, read about Code owners). Premium and Ultimate only.
      • Merged-By, for merge requests merged by this user.
      • Reviewer, for merge requests reviewed by this user.
  5. Select or type the operator to use for filtering the attribute. The following operators are available:
    • =: Is
    • !=: Is not
  6. Enter the text to filter the attribute by. You can filter some attributes by None or Any.
  7. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical AND.
  8. Select a Sort direction, either for descending order, or for ascending order.

By environment or deployment date

To filter merge requests by deployment data, such as the environment or a date, you can type (or select from the dropdown list) the following:

  • Environment
  • Deployed-before
  • Deployed-after
note
Projects using a fast-forward merge method do not return results, as this method does not create a merge commit.

When filtering by an environment, a dropdown list presents all environments that you can choose from.

When filtering by Deployed-before or Deployed-after:

  • The date refers to when the deployment to an environment (triggered by the merge commit) completed successfully.
  • You must enter the deploy date manually.
  • Deploy dates use the format YYYY-MM-DD, and must be wrapped in double quotes (") if you want to specify both a date and time ("YYYY-MM-DD HH:MM").

Add changes to a merge request

If you have permission to add changes to a merge request, you can add your changes to an existing merge request in several ways, depending on the complexity of your change and whether you need access to a development environment:

Assign a user to a merge request

To assign the merge request to a user, use the /assign @user quick action in a text area in a 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. On the right sidebar, expand the right sidebar and locate the Assignees section.
  4. Select Edit.
  5. Search for the user you want to assign, and select the user.

The merge request is added to the user’s assigned merge request list.

Assign multiple users

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
History
  • Moved to GitLab Premium in 13.9.

GitLab enables multiple assignees for merge requests, if multiple people are accountable for it:

multiple assignees for merge requests sidebar

To assign multiple assignees to a merge request, use the /assign @user quick action in a text area, 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. On the right sidebar, expand the right sidebar and locate the Assignees section.
  4. Select Edit and, from the dropdown list, select all users you want to assign the merge request to.

To remove an assignee, clear the user from the same dropdown list.

Close a merge request

If you decide to permanently stop work on a merge request, GitLab recommends you close the merge request rather than delete it. The author and assignees of a merge request, and users with Developer, Maintainer, or Owner roles in a project can close merge requests in the project:

  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. Scroll to the comment box at the bottom of the page.
  4. Following the comment box, select Close merge request.

GitLab closes the merge request, but preserves records of the merge request, its comments, and any associated pipelines.

Delete a merge request

GitLab recommends you close, rather than delete, merge requests. You cannot undo the deletion of a merge request.

Prerequisites:

  • You must have the Owner role for the project.

To delete a merge request:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests and find the merge request you want to delete.
  3. Select Edit.
  4. Scroll to the bottom of the page, and select Delete merge request.

Delete the source branch on merge

You can delete the source branch for a merge request:

  • When you create a merge request, by selecting Delete source branch when merge request accepted.
  • When you merge a merge request, if you have the Maintainer role, by selecting Delete source branch.

An administrator can make this option the default in the project’s settings.

Update merge requests when target branch merges

Tier: Free, Premium, Ultimate Offering: Self-managed
History
  • Chained merge requests changed to automatically rebase on the new target branch in GitLab 16.9.
  • Chained merge requests no longer automatically rebase on the new target branch in GitLab 16.10 with a flag named :rebase_when_retargetting_mrs. Disabled by default.
On self-managed GitLab, by default this feature is not available. To make it available, an administrator can enable the feature flag named :rebase_when_retargetting_mrs. On GitLab.com and GitLab Dedicated, this feature is not available.

Merge requests are often chained together, with one merge request depending on the code added or changed in another merge request. To support keeping individual merge requests small, GitLab can update up to four open merge requests when their target branch merges into main. For example:

  • Merge request 1: merge feature-alpha into main.
  • Merge request 2: merge feature-beta into feature-alpha.

If these merge requests are open at the same time, and merge request 1 (feature-alpha) merges into main, GitLab updates the destination of merge request 2 from feature-alpha to main.

Merge requests with interconnected content updates are usually handled in one of these ways:

  • Merge request 1 is merged into main first. Merge request 2 is then retargeted to main.
  • Merge request 2 is merged into feature-alpha. The updated merge request 1, which now contains the contents of feature-alpha and feature-beta, is merged into main.

This feature works only when a merge request is merged. Selecting Remove source branch after merging does not retarget open merge requests. This improvement is proposed as a follow-up.

Move sidebar actions

History
  • Introduced in GitLab 14.10 with a flag named moved_mr_sidebar. Enabled by default.
  • Changed to also move actions on issues, incidents, and epics in GitLab 16.0.

When this feature flag is enabled, in the upper-right corner, Merge request actions ( ) contains the following actions:

In GitLab 16.0 and later, similar action menus are available on issues, incidents, and epics.

When this feature flag is disabled, these actions are in the right sidebar.

Merge request workflows

For a software developer working in a team:

  1. You check out a new branch, and submit your changes through a merge request.
  2. You gather feedback from your team.
  3. You work on the implementation optimizing code with Code Quality reports.
  4. You verify your changes with Unit test reports in GitLab CI/CD.
  5. You avoid using dependencies whose license is not compatible with your project with License approval policies.
  6. You request the approval from your manager.
  7. Your manager:
    1. Pushes a commit with their final review.
    2. Approves the merge request.
    3. Sets it to auto-merge (formerly Merge when pipeline succeeds).
  8. Your changes get deployed to production with manual jobs for GitLab CI/CD.
  9. Your implementations were successfully shipped to your customer.

For a web developer writing a webpage for your company’s website:

  1. You check out a new branch and submit a new page through a merge request.
  2. You gather feedback from your reviewers.
  3. You preview your changes with Review Apps.
  4. You request your web designers for their implementation.
  5. You request the approval from your manager.
  6. Once approved, your merge request is squashed and merged, and deployed to staging with GitLab Pages.
  7. Your production team cherry-picks the merge commit into production.

Filter activity in a merge request

History

To understand the history of a merge request, filter its activity feed to show you only the items that are relevant to you.

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests.
  3. Select a merge request.
  4. Scroll to Activity.
  5. On the right side of the page, select Activity filter to show the filter options. If you’ve selected filter options previously, this field shows a summary of your choices, like Activity + 5 more.
  6. Select the types of activity you want to see. Options include:

    • Assignees & Reviewers
    • Approvals
    • Comments (from bots)
    • Comments (from users)
    • Commits & branches
    • Edits
    • Labels
    • Lock status
    • Mentions
    • Merge request status
    • Tracking
  7. Optional. Select Sort ( ) to reverse the sort order.

Your selection persists across all merge requests. You can also change the sort order by clicking the sort button on the right.

Resolve a thread

When you want to finish a conversation in a merge request, resolve a thread.

The number of unresolved threads is shown in the top right corner of a merge request, like this: 7 unresolved threads.

Move all unresolved threads in a merge request to an issue

If you have multiple unresolved threads in a merge request, you can create an issue to resolve them separately:

  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. In the merge request, in the top right, find the Unresolved threads dropdown list, and select Thread options ( ).
  4. Select Resolve all with new issue.
  5. Fill out the fields in the new issue, and select Create issue.

All threads are marked as resolved, and a link is added from the merge request to the newly created issue.

Move one unresolved thread in a merge request to an issue

If you have one specific unresolved thread in a merge request, you can create an issue to resolve it separately:

  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. In the merge request, find the thread you want to move.
  4. Below the last reply to the thread, next to Resolve thread, select Create issue to resolve thread ( ).
  5. Fill out the fields in the new issue, and select Create issue.

The thread is marked as resolved, and a link is added from the merge request to the newly created issue.

Prevent merge unless all threads are resolved

You can prevent merge requests from being merged until all threads are resolved. When this setting is enabled, the Unresolved threads counter in a merge request is shown in orange when at least one thread remains unresolved.

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Merge requests.
  3. In the Merge checks section, select the All threads must be resolved checkbox.
  4. Select Save changes.

Automatically resolve threads in a merge request when they become outdated

You can set merge requests to automatically resolve threads when lines are modified with a new push.

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Merge requests.
  3. In the Merge options section, select Automatically resolve merge request diff threads when they become outdated.
  4. Select Save changes.

Threads are now resolved if a push makes a diff section outdated. Threads on lines that don’t change and top-level resolvable threads are not resolved.

Move notifications and to-dos

DETAILs: Tier: Free, Premium, Ultimate Offering: Self-managed

History
On self-managed GitLab, by default this feature is not available. To make it available, an administrator can enable the feature flag named notifications_todos_buttons. On GitLab.com and GitLab Dedicated, this feature is not available.

When this feature flag is enabled, the notifications and to-do item buttons are moved to the upper right corner of the page.

  • On merge requests, these buttons are located to the far right of the tabs.
  • On issues, incidents, and epics, these buttons are located at the top of the right sidebar.