Creating merge requests · Merge requests · Project · User · Help · GitLab

Creating merge requests · Merge requests · Project · User · Help · GitLab
Admin message
Due to an influx of spam, we have had to require each new account to be manually approved. Please register an account and then write an email to
accountsupport@archlinux.org
to get it approved. Sorry for the inconvenience.
Create merge requests
Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
When you're ready to create a merge request, use a method that fits your workflow. You can create a merge request:
In the GitLab UI.
From the command line, with the
glab mr
command, or Git commands combined with
push options
In the
Visual Studio Code extension
By sending an email.
With
the merge requests API
When you create a merge request, GitLab enforces your project's branch naming rules.
To connect your merge request to a branch, follow
branch naming patterns
Merge request titles have
limited formatting support
From the top bar
You can create a merge request from the top bar in a project:
On the top bar, select
Search or go to
and find your project.
In the upper-right corner, select
Create new
{plus}
) and
New merge request
From the merge request list
You can create a merge request from the list of merge requests.
In the top bar, select
Search or go to
and find your project.
In the left sidebar, select
Code
Merge requests
In the upper-right corner, select
New merge request
Select a source and target branch, then select
Compare branches and continue
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
New branch from an issue
To create a branch and a merge request at the same time:
In the top bar, select
Search or go to
and find your project.
Select
Plan
Work items
, then filter by
Type
Issue
and select your issue.
Go to the bottom of the issue description.
Select
Create merge request
Create merge request and branch
On the dialog, review the suggested branch name. It's based on your project's
branch name template
Optional. If the branch name is already taken, or you need a different branch name, rename it.
Select a source branch or tag.
Select
Create merge request
Existing branch from an issue
Version history
Introduced
in GitLab 17.11.
Prerequisites:
A branch must already be linked to the issue.
You must have permission to create merge requests in the project.
To create a merge request when a branch is already linked in Development:
In the top bar, select
Search or go to
and find your project.
Select
Plan
Work items
, then filter by
Type
Issue
and select your issue.
In the
Development
section, find the linked branch.
Select the branch actions menu (
{ellipsis_v}
).
Select
Create merge request
Complete the fields on the
New merge request
page, then select
Create merge request
The merge request form is pre-filled with the appropriate keywords to link it back to the issue.
From a task
Version history
Introduced
in GitLab 17.8.
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
New branch from a task
Prerequisites:
You must have the Developer, Maintainer, or Owner role for the project containing the task.
To create a branch and a merge request at the same time:
In the top bar, select
Search or go to
and find your project.
Select
Plan
Work items
, then filter by
Type
Task
and select your task.
Go to the bottom of the task description.
Select
Create merge request
On the dialog, review the suggested branch name.
It's based on your project's
branch name template
Optional. If the branch name is already taken, or you need a different branch name, rename it.
Select a source branch or tag.
Select
Create merge request
Existing branch from a task
Version history
Introduced
in GitLab 17.11.
Prerequisites:
A branch must already be linked to the task.
You must have permission to create merge requests in the project.
To create a merge request when a branch is already linked in Development:
In the top bar, select
Search or go to
and find your project.
Select
Plan
Work items
, then filter by
Type
Task
and select your task.
In the
Development
section, find the linked branch.
Select the branch actions menu (
{ellipsis_v}
).
Select
Create merge request
Complete the fields on the
New merge request
page, then select
Create merge request
The merge request form is pre-filled with the appropriate keywords to link it back to the task.
When your Git repository is empty
If your Git repository is empty when you create a merge request from an issue or task, 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 or task title.
If your project is configured with a deployment service like Kubernetes,
prompts you to set up
auto deploy
by helping you create a
.gitlab-ci.yml
file.
Automatic issue and task closing
If the name of the branch you create is
prefixed with the issue or task number
GitLab cross-links the issue or task 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 issue or task. If your project is configured with a
closing pattern, the issue or task closes when the merge request merges.
From the Web Editor
You can create merge requests with the
Web Editor
when you:
Create, edit, upload, or delete a file.
Create a directory.
When you create a branch
You can create a merge request when you create a branch.
In the top bar, select
Search or go to
and find your project.
In the left sidebar, select
Code
Branches
Type a branch name and select
New branch
Above the file list, select
Create merge request
A merge request is created. The default branch is the target.
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.
In the top bar, select
Search or go to
and find your fork.
In the left sidebar, select
Code
Merge requests
, and select
New merge request
For
Source branch
, select the branch in your fork that contains your changes.
For
Target branch
Select the upstream repository, and not your fork.
If you contribute changes upstream frequently, consider setting a
default target for your fork.
Select a branch from the upstream repository:
Note
If your fork's visibility is more restricted than the parent repository, the target branch
defaults to your fork's default branch. This prevents potential exposure of private
information in your fork.
Select
Compare branches and continue
Select
Create merge request
. The merge request is created in the target repository,
not your fork.
If you are assigned the Developer, Maintainer, or Owner role, add your desired assignees, reviewers, labels,
and milestones.
Select
Submit merge request
If the merge request targets another repository, it uses:
The target project's approval rules.
Your fork's CI/CD configuration, resources, and project CI/CD variables.
To run CI/CD pipelines in the upstream project,
you must be a member of that project
If you run a merge request pipeline in the parent project
for a merge request from a fork, all variables become available to the pipeline.
After your work merges,
unlink your fork
from its upstream repository if you don't intend to make more contributions.
Set the default target project
By default, merge requests originating from a fork target the upstream repository, not your fork.
You can configure your forked repository to be the default target, rather than the upstream repository.
Prerequisites:
You're working in a fork.
You must have the Developer, Maintainer, or Owner role, or be allowed to create merge requests in the project.
The upstream repository 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:
In the top bar, select
Search or go to
and find your project.
Select
Settings
Merge requests
In the
Target project
section, select the option you want to use for
your default target project.
Select
Save changes
By sending an email
Version history
Email a new merge request to this project
renamed
to
Email merge request to this project
in GitLab 18.6.
You can create a merge request by sending an email message to GitLab.
The merge request target branch is the repository's default branch.
Prerequisites:
The merge request must target the current repository, not an upstream repository.
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 the Developer, Maintainer, or Owner role, or be allowed to create merge requests in the project.
To create a merge request by sending an email:
In the top bar, select
Search or go to
and find your project.
In the left sidebar, select
Code
Merge requests
If the project contains any merge requests, select
Email merge request to this project
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.
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.
To add commits, attach
.patch
files to the message.
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.
Related topics
Merge requests API
Quick actions
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, you can't restore the fork relationship. Your project can no longer
send or receive merge requests to the source project, or other forks of it.
Email message could not be processed
When sending an email to create a merge request, and you attempt to target an
upstream repository, 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.