Creating merge requests
Merge requests are the primary method of making changes to files in a GitLab project. Changes are proposed by creating and submitting a merge request, which is then reviewed, and accepted (or rejected), all within GitLab.
Creating new merge requests
You can start creating a new merge request by clicking the New merge request button on the Merge Requests page in a project. Then you must choose the source project and branch that contain your changes, and the target project and branch where you want to merge the changes into. Click on Compare branches and continue to go to the next step and start filling in the merge request details.
When viewing the commits on a branch other than master in Repository > Commits, you
can click on the Create merge request button, and a new merge request will be started
using the current branch as the source, and
master in the current project as the target.
If you have recently pushed changes to GitLab, the Create merge request button will also appear in the top right of the:
- Project page.
- Repository > Files page.
- Merge Requests page.
In this case, the merge request will use the most recent branch you pushed changes
to as the source branch, and
master in the current project as the target.
You can also create a new merge request directly from an issue.
Workflow for new merge requests
On the New Merge Request page, you can start by filling in the title and description for the merge request. If there are are already commits on the branch, the title will be pre-filled with the first line of the first commit message, and the description will be pre-filled with any additional lines in the commit message. The title is the only field that is mandatory in all cases.
From here, you can also:
- Set the merge request as a work in progress.
- Select the assignee, or assignees. (STARTER)
- Select a milestone.
- Select labels.
- Add any merge request dependencies. (PREMIUM)
- Select approval options. (STARTER)
- Verify the source and target branches are correct.
- Enable the delete source branch when merge request is accepted option.
- Enable the squash commits when merge request is accepted option.
- If the merge request is from a fork, enable Allow collaboration on merge requests across forks.
Many of these can be set when pushing changes from the command line, with Git push options.
Merge requests to close issues
If the merge request is being created to resolve an issue, you can add a note in the description which will set it to automatically close the issue when merged.
Choose an assignee to designate someone as the person responsible for the first review of the merge request. Open the drop down box to search for the user you wish to assign, and the merge request will be added to their assigned merge request list.
Multiple assignees (STARTER)
Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests to indicate everyone that is reviewing or accountable for it.
To assign multiple assignees to a merge request:
- From a merge request, expand the right sidebar and locate the Assignees section.
- Click on Edit and from the dropdown menu, select as many users as you want to assign the merge request to.
Similarly, assignees are removed by deselecting them from the same dropdown menu.
It's also possible to manage multiple assignees:
- When creating a merge request.
- Using quick actions.
Deleting the source branch
When creating a merge request, select the "Delete source branch when merge request accepted" option and the source branch will be deleted when the merge request is merged. To make this option enabled by default for all new merge requests, enable it in the project's settings.
This option is also visible in an existing merge request next to the merge request button and can be selected/deselected before merging. It's only visible to users with Maintainer permissions in the source project.
If the user viewing the merge request does not have the correct permissions to delete the source branch and the source branch is set for deletion, the merge request widget will show the "Deletes source branch" text.
Create new merge requests by email
This feature needs incoming email to be configured by a GitLab administrator to be available for CE/EE users, and it's available on GitLab.com.
You can create a new merge request by sending an email to a user-specific email address. The address can be obtained on the merge requests page by clicking on a Email a new merge request to this project button. The subject will be used as the source branch name for the new merge request and the target branch will be the default branch for the project. The message body (if not empty) will be used as the merge request description. You need "Reply by email" enabled to use this feature. If it's not enabled to your instance, you may ask your GitLab administrator to do so.
This is a private email address, generated just for you. Keep it to yourself as anyone who gets ahold of it can create issues or merge requests as if they were you. You can add this address to your contact list for easy access.
In GitLab 11.7, we updated the format of the generated email address. However the older format is still supported, allowing existing aliases or contacts to continue working.
Adding patches when creating a merge request via e-mail
Introduced in GitLab 11.5.
You can add commits to the merge request being created by adding
patches as attachments to the email. All attachments with a filename
.patch will be considered patches and they will be processed
ordered by name.
The combined size of the patches can be 2MB.
If the source branch from the subject does not exist, it will be
created from the repository's HEAD or the specified target branch to
apply the patches. The target branch can be specified using the
/target_branch quick action. If the source
branch already exists, the patches will be applied on top of it.