1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
---
stage: Create
group: Code Review
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
type: howto
description: "How to create Merge Requests in GitLab."
disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html'
---
# How to create a merge request **(FREE)**
Before creating a merge request, read through an
[introduction to Merge Requests](getting_started.md)
to familiarize yourself with the concept, the terminology,
and to learn what you can do with them.
Every merge request starts by creating a branch. You can either
do it locally through the [command line](#new-merge-request-from-your-local-environment), via a Git CLI application,
or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through-the-ui).
This document describes the several ways to create a merge request.
When you start a new merge request, regardless of the method,
you are taken to the [**New Merge Request** page](#new-merge-request-page)
to fill it with information about the merge request.
If you push a new branch to GitLab, also regardless of the method,
you can click the [**Create Merge Request**](#create-merge-request-button)
button and start a merge request from there.
## New Merge Request page
On the **New Merge Request** page, start by filling in the title and description
for the merge request. If commits already exist on the branch, GitLab suggests a
merge request title for you:
- **If a multi-line commit message exists**: GitLab adds the first line of the
first multi-line commit message as the title. Any additional lines in that
commit message become the description.
- **If no multi-line commit message exists**: GitLab adds the branch name as the
title, and leaves the description blank.
The title is the only field that is mandatory in all cases.
From there, you can fill it with information (title, description,
assignee(s), milestone, labels, approvers) and click **Create Merge Request**.
From that initial screen, you can also see all the commits,
pipelines, and file changes pushed to your branch before submitting
the merge request.
NOTE:
You can push one or more times to your branch in GitLab before
creating the merge request.
## Create Merge Request button
Once you have pushed a new branch to GitLab, visit your repository
in GitLab and to see a call-to-action at the top of your screen
from which you can click the button **Create Merge Request**.
You can also see the **Create merge request** button in the top-right of the:
- **Project** page.
- **Repository > Files** page.
- **Merge Requests** page.
In this case, GitLab uses the most recent branch you pushed
changes to as the source branch, and the default branch in the current
project as the target.
## New merge request by adding, editing, and uploading a file
When you choose to edit, add, or upload a file through the GitLab UI,
at the end of the file you see the option to add the **Commit message**,
to select the **Target branch** of that commit, and the checkbox to
**Start new a merge request with these changes**.
Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you see these same options.
Once you have added, edited, or uploaded the file:
1. Describe your changes in the commit message.
1. Select an existing branch to add your commit into, or, if you'd like to create a new branch, type the new branch name (without spaces, capital letters, or special chars).
1. Keep the checkbox checked to start a new merge request straightaway, or, uncheck it to add more changes to that branch before starting the merge request.
1. Click **Commit changes**.
If you chose to start a merge request, you are taken to the
[**New Merge Request** page](#new-merge-request-page), from
which you can fill it in with information and submit the merge request.
The merge request targets the default branch of the repository.
If you want to change it, you can do it later by editing the merge request.
## New merge request from a new branch created through the UI
To quickly start working on files through the GitLab UI,
navigate to your project's **Repository > Branches** and click
**New branch**. A new branch is created and you can start
editing files.
Once committed and pushed, you can click on the [**Create Merge Request**](#create-merge-request-button)
button to open the [**New Merge Request** page](#new-merge-request-page).
A new merge request is started using the current branch as the source,
and the default branch in the current project as the target.
## New merge request from your local environment
Assuming you have your repository cloned into your computer and you'd
like to start working on changes to files, start by creating and
checking out a new branch:
```shell
git checkout -b my-new-branch
```
Work on your file changes, stage, and commit them:
```shell
git add .
git commit -m "My commit message"
```
Once you're done, [push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom):
```shell
git push origin my-new-branch
```
In the output, GitLab prompts you with a direct link for creating
a merge request:
```shell
...
remote: To create a merge request for docs-new-merge-request, visit:
remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch
```
Copy that link and paste it in your browser, and the [**New Merge Request page**](#new-merge-request-page)
is displayed.
There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI.
If you didn't push your branch to GitLab through the command line
(for example, you used a Git CLI application to push your changes),
you can create a merge request through the GitLab UI by clicking
the [**Create Merge Request**](#create-merge-request-button) button.
## New merge request from an issue
You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue).
## New merge request from the Merge Requests page
You can start creating a new merge request by clicking the
**New merge request** button on the **Merge Requests** page in a project.
Then 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
[**New Merge Request** page](#new-merge-request-page) and fill in the details.
## New merge request from a fork
After forking a project and applying your local changes, complete the following steps to
create a merge request from your fork to contribute back to the main project:
1. Go to **Projects > Your Projects** and select your fork of the repository.
1. In the left menu, go to **Merge Requests**, and click **New Merge Request**.
1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch.
1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch.
1. After entering the credentials, click **Compare branches and continue** to compare your local changes to the upstream repository.
1. Assign a user to review your changes, and click **Submit merge request**.
When the changes are merged, your changes are added to the upstream repository and
the branch as per specification. After your work is merged, if you don't intend to
make any other contributions to the upstream project, you can unlink your
fork from its upstream project in the **Settings > Advanced Settings** section by
[removing the forking relationship](../settings/index.md#removing-a-fork-relationship).
For further details, [see the forking workflow documentation](../repository/forking_workflow.md).
## New merge request by email **(FREE SELF)**
_This feature needs [incoming email](../../../administration/incoming_email.md)
to be configured by a GitLab administrator to be available._ It isn't
available in 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 is
used as the source branch name for the new merge request and the target branch
is the default branch for the project. The message body (if not empty)
is used as the merge request description. You need
["Reply by email"](../../../administration/reply_by_email.md) 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 has 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](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) 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` are considered patches and they are processed
ordered by name.
The combined size of the patches can be 2MB.
If the source branch from the subject does not exist, it is
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](../quick_actions.md). If the source
branch already exists, the patches are applied on top of it.
## Reviewing and managing Merge Requests
Once you have submitted a merge request, it can be [reviewed and managed](reviewing_and_managing_merge_requests.md) through GitLab.
|
