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.

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:

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.

If the issue is confidential, you may want to use a different workflow for merge requests for confidential issues, to prevent confidential information from being exposed.

Assignee

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

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.

multiple assignees for merge requests sidebar

To assign multiple assignees to a merge request:

  1. From a merge request, expand the right sidebar and locate the Assignees section.
  2. 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:

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.

Delete source branch status

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.

Create new merge requests by email

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 ending in .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.