Skip to content

G
gitlab-ce
Commit ae45670a authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Marcin Sedlak-Jakubowski
Browse files
Options

Edited "Create MRs" for style and CTRT

parent 7e8235a3
Show whitespace changes
Inline Side-by-side
Showing with 109 additions and 189 deletions
doc/administration/incoming_email.md
View file @ ae45670a
......@@ -13,7 +13,7 @@ GitLab has several features based on receiving incoming email messages:
- [New issue by email](../user/project/issues/managing_issues.md#new-issue-via-email):
allow GitLab users to create a new issue by sending an email to a
user-specific email address.
- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email):
- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email):
allow GitLab users to create a new merge request by sending an email to a
user-specific email address.
- [Service Desk](../user/project/service_desk.md): provide email support to
......@@ -95,7 +95,7 @@ email address to sign up.
If you also host a public-facing GitLab instance at `hooli.com` and set your
incoming email domain to `hooli.com`, an attacker could abuse the "Create new
issue by email" or
"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email)"
"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email)"
features by using a project's unique address as the email when signing up for
Slack. This would send a confirmation email, which would create a new issue or
merge request on the project owned by the attacker, allowing them to click the
......
doc/administration/index.md
View file @ ae45670a
......@@ -134,7 +134,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
- [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance.
- [Incoming email](incoming_email.md): Configure incoming emails to allow
users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and
[merge requests by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email), and to enable [Service Desk](../user/project/service_desk.md).
[merge requests by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email), and to enable [Service Desk](../user/project/service_desk.md).
- [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a
basic Postfix mail server with IMAP authentication on Ubuntu for incoming
emails.
......
doc/user/project/merge_requests/creating_merge_requests.md
View file @ ae45670a
......@@ -7,189 +7,155 @@ 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)**
# Creating merge requests **(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.
There are many different ways to create a merge request.
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).
## From the merge request list
This document describes the several ways to create a merge request.
You can create a merge request from the list of merge requests.
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.
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left menu, select **Merge requests**.
1. In the top right, select **New merge request**.
1. Select a source and target branch and then **Compare branches and continue**.
1. Fill out the fields and select **Create 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.
## From an issue
## New merge request page
You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue).
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:
## When you add, edit, or upload a file
- **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.
You can create a merge request when you add, edit, or upload a file to a repository.
The title is the only field that is mandatory in all cases.
1. Add, edit, or upload a file to the repository.
1. In the **Commit message**, enter a reason for the commit.
1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars).
1. 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.
1. Select **Commit changes**.
From there, you can fill it with information (title, description,
assignee(s), milestone, labels, approvers) and click **Create merge request**.
## When you create a branch
From that initial screen, you can also see all the commits,
pipelines, and file changes pushed to your branch before submitting
the merge request.
You can create a merge request when you create a branch.
![New merge request page](img/new_merge_request_page_v12_6.png)
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left menu, select **Repository > Branches**.
1. Type a branch name and select **New branch**.
1. Above the file list, on the right side, select **Create merge request**.
A merge request is created. The default branch is the target.
1. Fill out the fields and select **Create merge request**.
NOTE:
You can push one or more times to your branch in GitLab before
creating the merge request.
## When you use Git commands locally
## Create merge request button
You can create a merge request by running Git commands on your local machine.
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**.
1. Create a branch:
![Create merge request button](img/create_merge_request_button_v12_6.png)
```shell
git checkout -b my-new-branch
```
You can also see the **Create merge request** button in the top-right of the:
1. Create, edit, or delete files. The stage and commit them:
- **Project** page.
- **Repository > Files** page.
- **Merge requests** page.
```shell
git add .
git commit -m "My commit message"
```
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.
1. [Push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom):
## New merge request by adding, editing, and uploading a file
```shell
git push origin my-new-branch
```
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**.
GitLab prompts you with a direct link for creating a merge request:
Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you see these same options.
```plaintext
...
remote: To create a merge request for docs-new-merge-request, visit:
remote: https://gitlab.example.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch
```
Once you have added, edited, or uploaded the file:
1. Copy the link and paste it in your browser.
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**.
You can add other [flags 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 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.
## When you work in a fork
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.
You can create a merge request from your fork to contribute back to the main project.
## 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:
1. On the top bar, select **Menu > Project**.
1. Select your fork of the repository.
1. On the left menu, go to **Merge requests**, and select **New merge request**.
1. In the **Source branch** drop-down list box, select the 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.
You can set a [default target project](#set-the-default-target-project) to
change the default target branch (which can be useful if you are working in a
forked project).
1. Select **Compare branches and continue**.
1. Select **Submit merge request**.
```shell
git add .
git commit -m "My commit message"
```
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. Go to **Settings > Advanced Settings** and
[remove the forking relationship](../settings/index.md#removing-a-fork-relationship).
Once you're done, [push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom):
For more information, [see the forking workflow documentation](../repository/forking_workflow.md).
```shell
git push origin my-new-branch
```
## By sending an email **(FREE SELF)**
In the output, GitLab prompts you with a direct link for creating
a merge request:
> The format of the generated email address changed in GitLab 11.7.
The earlier format is still supported so existing aliases
or contacts still work.
```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
```
You can create a merge request by sending an email message to GitLab.
The merge request target branch is the project's default branch.
Copy that link and paste it in your browser, and the [**New merge request page**](#new-merge-request-page)
is displayed.
Prerequisites:
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.
- A GitLab administrator must configure [incoming email](../../../administration/incoming_email.md).
- A GitLab administrator must configure [Reply by email](../../../administration/reply_by_email.md).
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.
To create a merge request by sending an email:
## New merge request from an issue
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left menu, select **Merge requests**.
1. In the top right, select **Email a new merge request to this project**.
An email address is displayed. Copy this address.
Ensure you keep this address private.
1. Open an email and compose a message with the following information:
You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue).
- The **To** line is the email address you copied.
- The subject line is the source branch name.
- The message body is the merge request description.
## New merge request from the merge requests page
1. Send the email message.
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.
A merge request is created.
## New merge request from a fork
### Add attachments when creating a merge request by email
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:
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5.
1. On the top bar, select **Menu > Project**.
1. Select **Your Projects**, then 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.
You can set a [default target project](#set-the-default-target-project) to
change the default target branch (which can be useful when working with a
forked project).
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**.
You can add commits to a merge request by adding
patches as attachments to the email. All attachments with a filename
ending in `.patch` are considered patches and are processed
ordered by name.
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).
The combined size of the patches can be 2 MB.
For further details, [see the forking workflow documentation](../repository/forking_workflow.md).
If the source branch from the subject does not exist, it is
created from the repository's HEAD or the specified target branch.
You can specify the target branch by using the
[`/target_branch` quick action](../quick_actions.md). If the source
branch already exists, the patches are applied on top of it.
## Set the default target project
Merge requests have a source and a target project which are the same, unless
Merge requests have a source and a target project that are the same, unless
forking is involved. Creating a fork of the project can cause either of these
scenarios when you create a new merge request:
......@@ -197,57 +163,11 @@ scenarios when you create a new merge request:
option).
- You target your own fork.
If you want to have merge requests from a fork by default target your own fork
(instead of the upstream project), you can change the default by:
To have merge requests from a fork by default target your own fork
(instead of the upstream project), you can change the default.
1. In your project, go to **Settings > General > Merge requests**.
1. On the top bar, select **Menu > Project**.
1. On the left menu, select **Settings > General > Merge requests**.
1. In the **Target project** section, select the option you want to use for
your default target project.
1. Select **Save changes**.
## 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.
![Create new merge requests by email](img/create_from_email.png)
_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 email
> [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](reviews/index.md) through GitLab.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7