Creating merge requests

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

GitLab provides many different ways to create a merge request, including by using Git commands.

note
GitLab enforces branch naming rules to prevent problems, and provides branch naming patterns to streamline merge request creation.

From the merge request list

You can create a merge request from 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. In the upper-right corner, select New merge request.
  4. Select a source and target branch, then select Compare branches and continue.
  5. Complete the fields on the New merge request page, then select Create merge request.

Each branch can be associated with only one open merge request. If a merge request already exists for this branch, a link to the existing merge request is shown.

From an issue

If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. After merging the merge request, the issue is closed automatically, unless automatic issue closing is disabled:

Merge request and branch

To create a branch and a merge request at the same time:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Plan > Issues and find your issue.
  3. Go to the bottom of the issue description.
  4. Select Create merge request > Create merge request and branch.
  5. On the dialog, review the suggested branch name. It’s based on your project’s branch name template.1. Optional. If the branch name is already taken, or you need a different branch name, rename it.
  6. Select a source branch or tag.
  7. Select Create merge request.
Branch only

To create only a branch directly from an issue:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Plan > Issues and find your issue.
  3. Go to the bottom of the issue description.
  4. Select Create merge request > Create branch.
  5. In the dialog, review the suggested branch name. It’s based on your project’s branch name template Rename it if the branch name is already taken, or you need a different branch name.
  6. Select a source branch or tag.
  7. Select Create branch.

If your Git repository is empty, GitLab:

  • Creates a default branch.
  • Commits a blank README.md file to it.
  • Creates and redirects you to a new branch based on the issue title.
  • If your project is configured with a deployment service like Kubernetes, GitLab prompts you to set up auto deploy by helping you create a .gitlab-ci.yml file.

If the name of the branch you create is prefixed with the issue number, GitLab cross-links the issue and merge request, and adds the issue closing pattern to the description of the merge request. In most cases, this looks like Closes #ID, where ID is the ID of the issue. If your project is configured with a closing pattern, the issue closes when the merge request merges.

From a task

History

If your team breaks issues into tasks, you can create a branch directly from the task to speed the process up. The new branch, and later its merge request, are marked as related to this task. After merging the merge request, the task is closed automatically, unless automatic issue closing is disabled:

Prerequisites:

  • You must have at least a Developer role for the project containing the task.
Merge request and branch

To create a branch and a merge request at the same time:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Plan > Issues.
  3. In the issue list, find your task.
  4. Go to the bottom of the task description.
  5. Select Create merge request.
  6. On the dialog, review the suggested branch name. It’s based on your project’s branch name template.
  7. Optional. If the branch name is already taken, or you need a different branch name, rename it.
  8. Select a source branch or tag.
  9. Select Create merge request.
Branch only

To create only a branch directly from a task:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Plan > Issues.
  3. In the issue list, find your task.
  4. Go to the bottom of the task description.
  5. Select Create merge request > Create branch.
  6. On the dialog, review the suggested branch name. It’s based on your project’s branch name template.
  7. Optional. If the branch name is already taken, or you need a different branch name, rename it.
  8. Select a source branch or tag.
  9. Select Create branch.

If your Git repository is empty, GitLab:

  • Creates a default branch.
  • Commits a blank README.md file to it.
  • Creates and redirects you to a new branch based on the issue title.
  • If your project is configured with a deployment service like Kubernetes, GitLab prompts you to set up auto deploy by helping you create a .gitlab-ci.yml file.

If the name of the branch you create is prefixed with the task number, GitLab cross-links the issue and merge request, and adds the closing pattern to the description of the merge request. In most cases, this looks like Closes #ID, where ID is the ID of the task. If your project is configured with a closing pattern, the task closes when the merge request merges.

When you add, edit, or upload a file

You can create a merge request when you add, edit, or upload a file to a repository.

  1. Add, edit, or upload a file to the repository.
  2. In the Commit message, enter a reason for the commit.
  3. Select the Target branch or create a new branch by typing the name.
  4. Select the Start a new merge request with these changes checkbox or toggle. This checkbox or toggle is visible only if the target is not the same as the source branch, or if the source branch is protected.
  5. Select Upload file.
  6. Fill out the fields and select Create merge request.

When you create a branch

You can create a merge request when you create a branch.

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Branches.
  3. Type a branch name and select New branch.
  4. Above the file list, select Create merge request. A merge request is created. The default branch is the target.
  5. Fill out the fields and select Create merge request.

When you work in a fork

You can create a merge request from your fork to contribute back to the main project.

  1. On the left sidebar, select Search or go to and find your fork.
  2. Select Code > Merge requests, and select New merge request.
  3. For Source branch, select the branch in your fork that contains your changes.

  4. For Target branch:

    1. Select the target project. (Make sure to select the upstream project, rather than your fork.)
    2. Select a branch from the upstream repository.
    note
    If you contribute changes upstream frequently, consider setting a default target project for your fork.
  5. Select Compare branches and continue.
  6. Select Create merge request. The merge request is created in the target project, not your fork.

After your work merges, unlink your fork from its upstream project if you don’t intend to make more contributions.

For more information, see the forking workflow documentation.

Set the default target project

By default, merge requests originating from a fork target the upstream project, not the forked project.

You can configure your forked project to be the default target rather than the upstream project.

Prerequisites:

  • You’re working in a fork.
  • You must have at least the Developer role, or be allowed to create merge requests in the project.
  • The upstream project allows merge requests to be created.
  • The visibility settings for the fork must match, or be less strict than, the upstream repository. For example: this setting isn’t shown if your fork is private, but the upstream is public.

To do this:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Merge requests.
  3. In the Target project section, select the option you want to use for your default target project.
  4. Select Save changes.

By sending an email

You can create a merge request by sending an email message to GitLab. The merge request target branch is the project’s default branch.

Prerequisites:

  • The merge request must target the current project, not an upstream project.
  • A GitLab administrator must configure incoming email. This setting is enabled on GitLab.com.
  • A GitLab administrator must configure Reply by email. This setting is enabled on GitLab.com.
  • You must have at least the Developer role, or be allowed to create merge requests in the project.

To create a merge request by sending an email:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Merge requests.
  3. If the project contains any merge requests, select Email a new merge request to this project.
  4. In the dialog, copy the email address shown. Keep this address private. Anyone who has it can create issues or merge requests as if they were you.

  5. Open an email and compose a message with the following information:

    • The To line is the email address you copied.
    • The Subject is the source branch name.
    • The body of the email is the merge request description.
  6. To add commits, attach .patch files to the message.
  7. Send the email.

A merge request is created.

Add attachments when creating a merge request by email

Add commits to a merge request by adding patches as attachments to the email.

  • The combined size of the patches must be 2 MB or less.
  • To be considered a patch, the attachment’s filename must end in .patch.
  • Patches are processed in order by name.
  • If the source branch from the subject does not exist, it is created from the repository’s HEAD, or the default target branch. To change the target branch manually, use the /target_branch quick action.
  • If the source branch already exists, patches are applied on top of it.

Troubleshooting

No option to create a merge request on an issue

The option to Create merge request doesn’t display on an issue if:

  • A branch with the same name already exists.
  • A merge request already exists for this branch.
  • Your project has an active fork relationship.
  • Your project is private and the issue is confidential.

To make this button appear, one possible workaround is to remove your project’s fork relationship. After removal, the fork relationship cannot be restored. This project can no longer be able to receive or send merge requests to the source project, or other forks.

Email message could not be processed

When sending an email to create a merge request, and you attempt to target an upstream project, GitLab responds with this error: 

Unfortunately, your email message to GitLab could not be processed.

You are not allowed to perform this action. If you believe this is in error, contact a staff member.