- Create a merge request
- View merge requests
- Filter the list of merge requests
- Add changes to a merge request
- Assign a user to a merge request
- Merge a merge request
- Close a merge request
- Merge request workflows
- Filter activity in a merge request
- Resolve a thread
- Move notifications and to-dos
- Related topics
Merge requests
- Sidebar actions menu
in GitLab 16.9. Feature flag
moved_mr_sidebar
removed.
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 | Groupdefault.md
| Instancedefault.md
| Projectdefault.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 * |
View merge requests
You can view merge requests for your project, group, or yourself.
To view all merge requests assigned to you, use the Shift + m keyboard shortcut, or:
- On the left sidebar, select Search or go to.
- From the dropdown list, select Merge requests assigned to me.
or:
- On the left sidebar, select Code > Merge requests ().
- From the dropdown list, select Assigned.
To view all merge requests for a project:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests.
Or, to use a keyboard shortcut, press g + m.
To view merge requests for all projects in a group:
- On the left sidebar, select Search or go to and find your group.
- Select Code > Merge requests.
If your group contains subgroups, this view also displays merge requests from the subgroup projects.
Filter the list of merge requests
To filter the list of merge requests:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests.
- Above the list of merge requests, select Search or filter results.
- 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.
- Select or type the operator to use for filtering the attribute. The following operators are
available:
-
=
: Is -
!=
: Is not
-
- Enter the text to filter the attribute by. You can filter some attributes by None or Any.
- Repeat this process to filter by more attributes, joined by a logical
AND
. - 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
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
. Wrap them 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. These ways depend on the complexity of your change, and whether you need access to a development environment:
- Edit changes in the Web IDE in your browser with the . keyboard shortcut. Use this browser-based method to edit multiple files, or if you are not comfortable with Git commands. You cannot run tests from the Web IDE.
- Edit changes in Gitpod, if you need a fully-featured environment to both edit files, and run tests afterward. Gitpod supports running the . To use Gitpod, you must enable Gitpod in your user account.
- Push changes from the command line, if you are familiar with Git and the command line.
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:
- 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, expand the right sidebar and locate the Assignees section.
- Select Edit.
-
Search for the user you want to assign, and select the user. GitLab Free allows one assignee per merge request, but GitLab Premium and GitLab Ultimate allow multiple assignees:
GitLab adds the merge request to the user’s Assigned merge requests page.
Merge a merge request
During the merge request review process, reviewers provide feedback on your merge request. When a reviewer decides that the contents of your merge request are acceptable, the reviewer can set auto-merge on it, even if some merge checks are failing. When a merge request is set to auto-merge, it merges after all merge checks pass, without more action from you.
Close a merge request
If you decide to permanently stop work on a merge request, close it rather than deleting it.
Prerequisites:
- You must be the author or assignees of the merge request, or
- You must have the Developer, Maintainer, or Owner roles in a project.
To close merge requests in the project:
- On the left sidebar, select Search or go to and find your project.
- Select Code > Merge requests and find your merge request.
- Scroll to the comment box at the bottom of the page.
- 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 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
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
intomain
. -
Merge request 2: merge
feature-beta
intofeature-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 merges into
main
first. Merge request 2 is then retargeted tomain
. - Merge request 2 merges into
feature-alpha
. The updated merge request 1, which now contains the contents offeature-alpha
andfeature-beta
, merges intomain
.
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
.
For a software developer working in a team:
For a web developer writing a webpage for your company’s website:
To understand the history of a merge request, filter its activity feed to show you
only the items that are relevant to you.
Select the types of activity you want to see. Options include:
Your selection persists across all merge requests. You can also change the
sort order by clicking the sort button on the right.
When you want to finish a conversation in a merge request,
resolve a thread.
GitLab shows the number of unresolved threads in the top right corner of a
merge request, like this: 7 unresolved threads.
If you have multiple unresolved threads in a merge request, you can
create an issue to resolve them separately:
GitLab marks all threads as resolved, and adds a link from the merge request to
the newly created issue.
If you have one specific unresolved thread in a merge request, you can
create an issue to resolve it separately:
GitLab marks the thread as resolved, and adds a link from the merge request to
the newly created issue.
You can prevent merge requests from merging while threads remain unresolved.
When you enable this setting, the Unresolved threads counter in a merge request
is shown in orange while at least one thread remains unresolved.
You can set merge requests to automatically resolve threads when a new push
changes the lines they describe.
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.
DETAILs:
Tier: Free, Premium, Ultimate
Offering: Self-managed
Enabling this feature flag moves the notifications and to-do item buttons to the upper right corner of the page.
Merge request workflows
Filter activity in a merge request
Resolve a thread
Move all unresolved threads in a merge request to an issue
Move one unresolved thread in a merge request to an issue
Prevent merge unless all threads are resolved
Automatically resolve threads in a merge request when they become outdated
Move notifications and to-dos
notifications_todos_buttons
. Disabled by default.
notifications_todos_buttons
.
On GitLab.com and GitLab Dedicated, this feature is not available.
Related topics