diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index ec269bec84d552df66fe52600f947590d9ab5f0b..e19f31c1388951b6ae31069e524b33b7ad343d8e 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -7,78 +7,52 @@ description: "How to create merge requests in GitLab." # Creating merge requests **(FREE ALL)** -GitLab provides many different ways to create a merge request. +You can create a merge request on the GitLab UI, by email, or with Git commands. -NOTE: -GitLab enforces [branch naming rules](../repository/branches/index.md#name-your-branch) -to prevent problems, and provides -[branch naming patterns](../repository/branches/index.md#prefix-branch-names-with-issue-numbers) -to streamline merge request creation. +To create a merge request, you must follow the branch name guide. For more information on branch name rules, see [Name your branch](../repository/branches/index.md#name-your-branch). ## 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. -1. Select **Code > Merge requests**. +1. On the left sidebar, select **Merge requests**. 1. In the upper-right corner, 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**. +1. Select the source branch that contains your changes. +1. Select the target branch you want to merge your changes into. +1. Select **Compare branches and continue**. +1. On the **New merge request** page, complete the fields. +1. Select **Create merge request**. -NOTE: -Merge requests are designed around a one-to-one (1:1) branch relationship. Only one open merge request may -be associated with a given target branch at a time. +Merge requests follow a one-to-one branch relationship. Each target branch can have +only one open merge request at a time. ## From an issue -> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. - -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](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown list below the issue description. - -NOTE: -In GitLab 14.8 and later, selecting **Create merge request** -[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) -instead of immediately creating the merge request. - -**Create merge request** doesn't display 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](../repository/forking_workflow.md#unlink-a-fork). -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. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) the Create merge request button to open the merge request creation form in GitLab 14.8. -The dropdown list contains the options **Create merge request and branch** and **Create branch**. +You can create a merge request and a branch, or only a branch, from an issue. When you create a merge request from an issue, the new branch and merge request are marked as related to the issue. The issue automatically closes when the merge request is complete unless automatic issue closing is off. For more information, see [Disable automatic issue closing](../issues/managing_issues.md#disable-automatic-issue-closing). -After selecting one of these options, a new branch or branch and merge request -is created based on your project's [default branch](../repository/branches/default.md). -The branch name is based on your project's [branch name template](../repository/branches/index.md), -but this value can be changed. +To create a merge request and branch from an issue: -When you select **Create branch** in an empty -repository project, GitLab performs these actions: - -- 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](../integrations/index.md) like Kubernetes,_ - GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) - by helping you create a `.gitlab-ci.yml` file. +1. On the left sidebar, select **Search or go to** and find your project. +1. On the left sidebar, select **Issues** and find your issue. +1. At the bottom of the issue description, select the **Create merge request** + dropdown list. +1. In the dialog, make sure **Create merge request and branch** is selected. +1. If you don't want to use the default branch name, enter a different **Branch name**. +1. If you want to base your merge request on a tag, or a branch other than + the project's default branch, enter a **Source** branch. +1. Select **Create merge request** to open the merge request form. +1. Complete the fields in the **New merge request** form, then select **Create merge request**. After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly-created branch, +the issue. When a merge request is created from the new branch, the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) `Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the -merge request is merged. +merge request is merged. + +When you create a branch from an issue, the issue ID is automatically included in the branch name. To change the default pattern, see [Configure default pattern for branch names from issues](../issues/managing_issues.md#closing-issues-automatically). You can also begin your Git branch name with the issue number and a hyphen to link a merge request to an issue. For more information, see [Prefix branch names with issue numbers](../repository/branches/index.md#prefix-branch-names-with-issue-numbers). ## When you add, edit, or upload a file @@ -221,3 +195,16 @@ To have merge requests from a fork by default target your own fork 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. + +## Troubleshooting + +You might not find the **Create merge request** option on your issue page. + +Create merge request will not display 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 restore **Create merge request** on your issue page, you can remove your project's fork relationship. Aftter you remove a fork relationship, you cannot send merge requests from your project to the source project. For more information, see [Unlink a fork](../repository/forking_workflow.md#unlink-a-fork).