From 6ed4ec3e0b1340f96b7c043ef51d1b33bbe85fde Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Mon, 19 Sep 2022 23:18:09 +0000 Subject: Add latest changes from gitlab-org/gitlab@15-4-stable-ee --- doc/user/project/merge_requests/approvals/rules.md | 31 ++-- .../project/merge_requests/approvals/settings.md | 41 +++-- .../project/merge_requests/cherry_pick_changes.md | 154 +++++++++++------ .../project/merge_requests/commit_templates.md | 4 +- .../merge_requests/creating_merge_requests.md | 10 +- doc/user/project/merge_requests/csv_export.md | 4 +- doc/user/project/merge_requests/dependencies.md | 163 ++++++++++++++++++ doc/user/project/merge_requests/drafts.md | 4 +- doc/user/project/merge_requests/getting_started.md | 2 +- .../merge_requests/img/cancel-mwps_v15_4.png | Bin 0 -> 12914 bytes .../img/cherry_pick_changes_commit.png | Bin 13568 -> 0 bytes .../merge_requests/img/cherry_pick_changes_mr.png | Bin 7214 -> 0 bytes .../img/cherry_pick_mr_timeline_v12_9.png | Bin 29557 -> 0 bytes .../img/cherry_pick_mr_timeline_v15_4.png | Bin 0 -> 7678 bytes .../merge_requests/img/cherry_pick_v15_4.png | Bin 0 -> 10187 bytes .../merge_requests/img/dependencies_edit_v12_4.png | Bin 18741 -> 0 bytes .../merge_requests/img/dependencies_view_v15_3.png | Bin 0 -> 18558 bytes .../img/merge_when_pipeline_succeeds_enable.png | Bin 10186 -> 0 bytes .../img/merge_when_pipeline_succeeds_status.png | Bin 21397 -> 0 bytes doc/user/project/merge_requests/img/mwps_v15_4.png | Bin 0 -> 11146 bytes doc/user/project/merge_requests/index.md | 12 +- .../merge_requests/merge_request_dependencies.md | 144 +--------------- .../merge_requests/merge_when_pipeline_succeeds.md | 186 +++++++++++---------- doc/user/project/merge_requests/methods/index.md | 7 +- doc/user/project/merge_requests/revert_changes.md | 92 ++++++---- .../reviews/img/mr_summary_comment_v15_3.png | Bin 49186 -> 0 bytes .../reviews/img/mr_summary_comment_v15_4.png | Bin 0 -> 61841 bytes doc/user/project/merge_requests/reviews/index.md | 12 +- .../project/merge_requests/squash_and_merge.md | 5 +- doc/user/project/merge_requests/status_checks.md | 7 +- 30 files changed, 510 insertions(+), 368 deletions(-) create mode 100644 doc/user/project/merge_requests/dependencies.md create mode 100644 doc/user/project/merge_requests/img/cancel-mwps_v15_4.png delete mode 100644 doc/user/project/merge_requests/img/cherry_pick_changes_commit.png delete mode 100644 doc/user/project/merge_requests/img/cherry_pick_changes_mr.png delete mode 100644 doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png create mode 100644 doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png create mode 100644 doc/user/project/merge_requests/img/cherry_pick_v15_4.png delete mode 100644 doc/user/project/merge_requests/img/dependencies_edit_v12_4.png create mode 100644 doc/user/project/merge_requests/img/dependencies_view_v15_3.png delete mode 100644 doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png delete mode 100644 doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png create mode 100644 doc/user/project/merge_requests/img/mwps_v15_4.png delete mode 100644 doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png create mode 100644 doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_4.png (limited to 'doc/user/project/merge_requests') diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index c9278c19322..32548215054 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -32,8 +32,9 @@ use the default approval rules from the target (upstream) project, not the sourc To add a merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**, and then select **Add approval rule**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Select **Add approval rule**. 1. Add a human-readable **Rule name**. 1. Set the number of required approvals in **Approvals required**. A value of `0` makes [the rule optional](#configure-optional-approval-rules), and any number greater than `0` @@ -65,8 +66,9 @@ to existing merge requests: To edit a merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**, and then select **Edit**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Select **Edit** next to the rule you want to edit. 1. Optional. Change the **Rule name**. 1. Set the number of required approvals in **Approvals required**. The minimum value is `0`. 1. Add or remove eligible approvers, as needed: @@ -155,11 +157,11 @@ approve in these ways: If you add [code owners](../../code_owners.md) to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Locate **All eligible users** and select the number of approvals required: +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Locate the **All eligible users** rule, and select the number of approvals required: -![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v15_2.png) + ![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v15_2.png) You can also [require code owner approval](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch) @@ -182,9 +184,10 @@ granting them push access: and select the Reporter role for the user. 1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group-of-users), based on the Reporter role. -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select **Add approval rule** or **Update approval rule** and target the protected branch. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**, and either: + - For a new rule, select **Add approval rule** and target the protected branch. + - For an existing rule, select **Edit** and target the protected branch. 1. [Add the group](../../../group/manage.md#create-a-group) to the permission list. ![Update approval rule](img/update_approval_rule_v13_10.png) @@ -226,12 +229,12 @@ Approval rules are often relevant only to specific branches, like your approval rule for certain branches: 1. [Create an approval rule](#add-an-approval-rule). -1. Go to your project and select **Settings**. -1. Expand **Merge request (MR) approvals**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. 1. Select a **Target branch**: - To apply the rule to all branches, select **All branches**. - To apply the rule to all protected branches, select **All protected branches** (GitLab 15.3 and later). - - To apply the rule to a specific branch, select it from the list: + - To apply the rule to a specific branch, select it from the list. 1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 3ca8ddb508a..4fdf6d46b8b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -16,8 +16,8 @@ those rules are applied as a merge request moves toward completion. To view or edit merge request approval settings: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. +1. Go to your project and select **Settings > Merge requests**. +1. Expand **Approvals**. ### Approval settings @@ -44,9 +44,9 @@ You can further define what happens to existing approvals when commits are added By default, the author of a merge request cannot approve it. To change this setting: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Clear the **Prevent approval by author** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + clear the **Prevent approval by author** checkbox. 1. Select **Save changes**. Authors can edit the approval rule in an individual merge request and override @@ -68,9 +68,9 @@ the project level or [instance level](../../../admin_area/merge_requests_approva you can prevent committers from approving merge requests that are partially their own. To do this: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent approvals by users who add commits** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Prevent approvals by users who add commits**. If this checkbox is cleared, an administrator has disabled it [at the instance level](../../../admin_area/merge_requests_approvals.md), and it can't be changed at the project level. @@ -94,9 +94,9 @@ By default, users can override the approval rules you [create for a project](rul on a per-merge-request basis. If you don't want users to change approval rules on merge requests, you can disable this setting: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent editing approval rules in merge requests** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Prevent editing approval rules in merge requests**. 1. Select **Save changes**. This change affects all open merge requests. @@ -112,9 +112,9 @@ permission enables an electronic signature for approvals, such as the one define 1. Enable password authentication for the web interface, as described in the [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Require user password to approve** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Require user password to approve**. 1. Select **Save changes**. ## Remove all approvals when commits are added to the source branch @@ -123,9 +123,9 @@ By default, an approval on a merge request remains in place, even if you add mor after the approval. If you want to remove all existing approvals on a merge request when more changes are added to it: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Remove all approvals when commits are added to the source branch** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Remove all approvals when commits are added to the source branch**. 1. Select **Save changes**. Approvals aren't removed when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods) @@ -143,10 +143,9 @@ Prerequisite: To do this: -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge request approvals**. -1. Select **Remove approvals by Code Owners if their files changed**. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Remove approvals by Code Owners if their files changed**. 1. Select **Save changes**. ## Code coverage check approvals diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 14f3979cf34..2040995280e 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -7,61 +7,106 @@ type: reference, concepts # Cherry-pick changes **(FREE)** -GitLab implements Git's powerful feature to -[cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") -with a **Cherry-pick** button in merge requests and commit details. +In Git, *cherry-picking* is taking a single commit from one branch and adding it +as the latest commit on another branch. The rest of the commits in the source branch +are not added to the target. You should cherry-pick a commit when you need the +change contained in a single commit, but you can't or don't want to pull the +entire contents of that branch into another. -## Cherry-pick a merge request +You can use the GitLab UI to cherry-pick single commits or entire merge requests. +You can even cherry-pick a commit from [a fork of your project](#cherry-pick-into-a-project). -After the merge request has been merged, a **Cherry-pick** button displays -to cherry-pick the changes introduced by that merge request. +NOTE: +Support for tracking commits cherry-picked from the command line +is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). -![Cherry-pick merge request](img/cherry_pick_changes_mr.png) +## Cherry-pick example + +In this example of cherry-picking, a Git repository has two branches: `develop` and `main`. +This example shows a cherry-picked commit from one branch being added to another: + +```mermaid +gitGraph + commit id: "A" + branch develop + commit id:"B" + checkout main + commit id:"C" + checkout develop + commit id:"D" + checkout main + commit id:"E" + cherry-pick id:"B" + commit id:"G" + checkout develop + commit id:"H" +``` -After you select that button, a modal displays a -[branch filter search box](../repository/branches/index.md#branch-filter-search-box) -where you can choose to either: +In this example, a cherry-pick of commit `B` from the `develop` branch is added +after commit `E` in the `main` branch. -- Cherry-pick the changes directly into the selected branch. -- Create a new merge request with the cherry-picked changes. +Commit `G` is added after the cherry-pick. -### Track a cherry-pick +## Cherry-pick all changes from a merge request -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. +After a merge request is merged, you can cherry-pick all changes introduced +by the merge request: -When you cherry-pick a merge commit, GitLab displays a system note to the related merge -request thread. It crosslinks the new commit and the existing merge request. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**, and find your merge request. +1. Scroll to the merge request reports section, and find the **Merged by** report. +1. In the top right, select **Cherry-pick**: -![Cherry-pick tracking in merge request timeline](img/cherry_pick_mr_timeline_v12_9.png) + ![Cherry-pick merge request](img/cherry_pick_v15_4.png) +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. +## Cherry-pick a single commit -NOTE: -We only track cherry-pick executed from GitLab (both UI and API). Support for tracking cherry-picked commits through the command line -is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). +You can cherry-pick a single commit from multiple locations in your GitLab project. -## Cherry-pick a commit +### From a project's commit list -You can cherry-pick a commit from the commit details page: +To cherry-pick a commit from the list of all commits for a project: -![Cherry-pick commit](img/cherry_pick_changes_commit.png) +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Commits**. +1. Select the title of the commit you want to cherry-pick. +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -Similar to cherry-picking a merge request, you can cherry-pick the changes -directly into the target branch or create a new merge request to cherry-pick the -changes. +### From a merge request -When cherry-picking merge commits, the mainline is always the -first parent. If you want to use a different mainline, you need to do that -from the command line. +You can cherry-pick commits from any merge request in your project, regardless of +whether the merge request is open or closed. To cherry-pick a commit from the +list of commits included in a merge request: -Here's a quick example to cherry-pick a merge commit using the second parent as the -mainline: +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**, and find your merge request. +1. In the merge request's secondary menu, select **Commits** to display the commit details page. +1. Select the title of the commit you want to cherry-pick. +1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -```shell -git cherry-pick -m 2 7a39eb0 -``` +### From the file view of a repository -### Cherry-pick into a project +You can cherry-pick from the list of previous commits affecting an individual file +when you view that file in your project's Git repository: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files** and go to the file + changed by the commit. +1. Select **History**, then select the title of the commit you want to cherry-pick. +1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. + +## Cherry-pick into a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11 behind a [feature flag](../../feature_flags.md), disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0. @@ -70,25 +115,38 @@ You can cherry-pick merge requests from the same project, or forks of the same project, from the GitLab user interface: 1. In the merge request's secondary menu, select **Commits** to display the commit details page. -1. Select the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. +1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch: ![Cherry-pick commit](img/cherry_pick_into_project_v13_11.png) 1. Optional. Select **Start a new merge request** if you're ready to create a merge request. 1. Select **Cherry-pick**. +## View system notes for cherry-picked commits + +When you cherry-pick a merge commit in the GitLab UI or API, GitLab adds a system note +to the related merge request thread in the format **{cherry-pick-commit}** +`[USER]` **picked the changes into the branch** `[BRANCHNAME]` with commit** `[SHA]` `[DATE]`: + +![Cherry-pick tracking in merge request timeline](img/cherry_pick_mr_timeline_v15_4.png) + +The system note crosslinks the new commit and the existing merge request. +Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. + ## Related topics -- The [Commits API](../../../api/commits.md) enables you to add custom messages - to changes you cherry-pick through the API. +- Use the [Commits API](../../../api/commits.md) to add custom messages + to changes when you use the API to cherry-pick. - +When you cherry-pick a merge commit in the GitLab UI, the mainline is always the +first parent. Use the command line to cherry-pick with a different mainline. + +Here's a quick example to cherry-pick a merge commit using the second parent as the +mainline: + +```shell +git cherry-pick -m 2 7a39eb0 +``` diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 6f9bc452b96..99a1739b1a4 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -29,8 +29,8 @@ Prerequisite: To do this: -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General** and expand **Merge requests**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. 1. Depending on the type of template you want to create, scroll to either [**Merge commit message template**](#default-template-for-merge-commits) or [**Squash commit message template**](#default-template-for-squash-commits). diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index f30b20e9d34..1a44126f7ff 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -14,7 +14,7 @@ There are many different ways to create a merge request. You can create a merge request from the list of merge requests. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main 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**. @@ -43,7 +43,7 @@ You can create a merge request when you add, edit, or upload a file to a reposit You can create a merge request when you create a branch. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main 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**. @@ -90,7 +90,7 @@ to reduce the need for editing merge requests manually through the UI. You can create a merge request from your fork to contribute back to the main project. -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Main menu > Projects** and find your 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. @@ -120,7 +120,7 @@ Prerequisites: To create a merge request by sending an email: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main 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. @@ -165,7 +165,7 @@ scenarios when you create a new merge request: To have merge requests from a fork by default target your own fork (instead of the upstream project), you can change the default. -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Main menu > Projects** and find your 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. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 893b2bc6811..f997898f5a5 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Compliance 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 --- @@ -12,7 +12,7 @@ Export all the data collected from a project's merge requests into a comma-separ To export merge requests to a CSV file: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** . 1. Add any searches or filters. This can help you keep the size of the CSV file under the 15MB limit. The limit ensures the file can be emailed to a variety of email providers. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md new file mode 100644 index 00000000000..5b88e69357c --- /dev/null +++ b/doc/user/project/merge_requests/dependencies.md @@ -0,0 +1,163 @@ +--- +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: reference, concepts +--- + +# Merge request dependencies **(PREMIUM)** + +A single feature can span several merge requests, spread out across multiple projects, +and the order in which the work merges can be significant. Use merge request dependencies +when it's important to merge work in a specific order. Some examples: + +- Ensure changes to a required library are merged before changes to a project that + imports the library. +- Prevent a documentation-only merge request from merging before the feature work + is itself merged. +- Require a merge request updating a permissions matrix to merge, before merging work + from someone who hasn't yet been granted permissions. + +If your project `me/myexample` imports a library from `myfriend/library`, +you might want to update your project to use a new feature in `myfriend/library`. +However, if you merge changes to your project before the external library adds the +new feature, you would break the default branch in your project. A merge request +dependency prevents your work from merging too soon: + +```mermaid +graph TB + A['me/myexample' project] + B['myfriend/library' project] + C[Merge request #1:
Create new version 2.5] + D[Merge request #2:
Add version 2.5
to build] + A-->|contains| D + B---->|contains| C + D-.->|depends on| C + C-.->|blocks| D +``` + +You could mark your `me/myexample` merge request as a [draft](drafts.md) +and explain why in the comments. However, this approach is manual and does not scale, especially +if your merge request relies on several others in multiple projects. Instead, +use the draft (or ready) state to track the readiness of an individual +merge request, and a merge request dependency to enforce merge order. + +NOTE: +Merge request dependencies are a **PREMIUM** feature, but this restriction is +enforced only for the dependent merge request. A merge request in a **PREMIUM** +project can depend on a merge request in a **FREE** project, but a merge request +in a **FREE** project cannot be marked as dependent. + +## View dependencies for a merge request + +If a merge request is dependent on another, the merge request reports section shows +information about the dependency: + +![Dependencies in merge request widget](img/dependencies_view_v15_3.png) + +To view dependency information on a merge request: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and identify your merge request. +1. Scroll to the merge request reports area. Dependent merge requests display information + about the total number of dependencies set, such as + **(status-warning)** **Depends on 1 merge request being merged**. +1. Select **Expand** to view the title, milestone, assignee, and pipeline status + of each dependency. + +Until your merge request's dependencies all merge, your merge request +cannot be merged. The message +**Merge blocked: you can only merge after the above items are resolved** displays. + +### Closed merge requests + +Closed merge requests still prevent their dependents from being merged, because +a merge request can close regardless of whether or not the planned work actually merged. + +If a merge request closes and the dependency is no longer relevant, +remove it as a dependency to unblock the dependent merge request. + +## Create a new dependent merge request + +When you create a new merge request, you can prevent it from merging until after +other specific work merges, even if the merge request is in a different project. + +Prerequisites: + +- You must have at least the Developer role or be allowed to create merge requests in the project. +- The dependent merge request must be in a project in a **PREMIUM** or higher tier. + +To create a new merge request and mark it as dependent on another: + +1. [Create a new merge request](creating_merge_requests.md). +1. In **Merge request dependencies**, paste either the reference or the full URL + to the merge requests that should merge before this work merges. References + are in the form of `path/to/project!merge_request_id`. +1. Select **Create merge request**. + +## Edit a merge request to add a dependency + +You can edit an existing merge request and mark it as dependent on another. + +Prerequisite: + +- You must have at least the Developer role or be allowed to edit merge requests in the project. + +To do this: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and identify your merge request. +1. Select **Edit**. +1. In **Merge request dependencies**, paste either the reference or the full URL + to the merge requests that should merge before this work merges. References + are in the form of `path/to/project!merge_request_id`. + +## Remove a dependency from a merge request + +You can edit a dependent merge request and remove a dependency. + +Prerequisite: + +- You must have a role in the project that allows you to edit merge requests. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and identify your merge request. +1. Select **Edit**. +1. Scroll to **Merge request dependencies** and select **Remove** next to the reference + for each dependency you want to remove. + + NOTE: + Dependencies for merge requests you don't have access to are displayed as + **1 inaccessible merge request**, and can be removed the same way. +1. Select **Save changes**. + +## Troubleshooting + +### API support for managing merge request dependencies + +No API support exists for managing dependencies. For more information, read +[issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551). + +### Preserving dependencies on project import or export + +Dependencies are not preserved when projects are imported or exported. For more +information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549). + +### Complex merge order dependencies are unsupported + +GitLab supports direct dependencies between merge requests, but does not support +[indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393). + +Acceptable dependency patterns include: + +- A single merge request can directly depend on a single merge request. +- A single merge request can directly depend on multiple merge requests. +- Multiple merge requests can directly depend on a single merge request. + +The indirect, nested dependency between `myfriend/library!10` and `mycorp/example!100` shown in this example is not supported: + +```mermaid +graph LR; + A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1] + B-->|depends on| C[mycorp/example!100] +``` diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 4bb6034c0bd..695c6d7e612 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -20,6 +20,7 @@ the **Merge** button until you remove the **Draft** flag: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/228685) all support for using **WIP** in GitLab 14.8. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. +> `/draft` quick action as a toggle [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4. There are several ways to flag a merge request as a draft: @@ -29,8 +30,7 @@ There are several ways to flag a merge request as a draft: below the **Title** field. - **Commenting in an existing merge request**: Add the `/draft` [quick action](../quick_actions.md#issues-merge-requests-and-epics) - in a comment. This quick action is a toggle, and can be repeated to change the status - back to Ready. + in a comment. GitLab 15.4 [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) the toggle behavior of `/draft`. To mark a merge request as ready, use `/ready`. - **Creating a commit**: Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and adding this text again in a later commit doesn't mark the diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 09ee828ffd3..9475c0d60ab 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -66,7 +66,7 @@ After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. - [Perform inline code reviews](reviews/index.md). -- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. +- Add [merge request dependencies](dependencies.md) to restrict it to be merged only when other merge requests have been merged. - Preview continuous integration [pipelines on the merge request widget](widgets.md). - Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). diff --git a/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png b/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png new file mode 100644 index 00000000000..7ed780d4389 Binary files /dev/null and b/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png differ diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png b/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png deleted file mode 100644 index c98821548f8..00000000000 Binary files a/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png and /dev/null differ diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png b/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png deleted file mode 100644 index 8b51503419b..00000000000 Binary files a/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png and /dev/null differ diff --git a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png deleted file mode 100644 index 919b576fcc6..00000000000 Binary files a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png and /dev/null differ diff --git a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png new file mode 100644 index 00000000000..d18c4aaec20 Binary files /dev/null and b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png differ diff --git a/doc/user/project/merge_requests/img/cherry_pick_v15_4.png b/doc/user/project/merge_requests/img/cherry_pick_v15_4.png new file mode 100644 index 00000000000..174bb113961 Binary files /dev/null and b/doc/user/project/merge_requests/img/cherry_pick_v15_4.png differ diff --git a/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png b/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png deleted file mode 100644 index 4edf0648794..00000000000 Binary files a/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png and /dev/null differ diff --git a/doc/user/project/merge_requests/img/dependencies_view_v15_3.png b/doc/user/project/merge_requests/img/dependencies_view_v15_3.png new file mode 100644 index 00000000000..d044e28046f Binary files /dev/null and b/doc/user/project/merge_requests/img/dependencies_view_v15_3.png differ diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png deleted file mode 100644 index 9487264b41a..00000000000 Binary files a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png and /dev/null differ diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png deleted file mode 100644 index 70fa2efc855..00000000000 Binary files a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png and /dev/null differ diff --git a/doc/user/project/merge_requests/img/mwps_v15_4.png b/doc/user/project/merge_requests/img/mwps_v15_4.png new file mode 100644 index 00000000000..f042912d470 Binary files /dev/null and b/doc/user/project/merge_requests/img/mwps_v15_4.png differ diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 35ec075c674..500fb95c193 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -27,7 +27,7 @@ You can view merge requests for your project, group, or yourself. To view all merge requests for a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. Or, to use a [keyboard shortcut](../../shortcuts.md), press g + m. @@ -36,7 +36,7 @@ Or, to use a [keyboard shortcut](../../shortcuts.md), press g + To view merge requests for all projects in a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Merge requests**. If your group contains subgroups, this view also displays merge requests from the subgroup projects. @@ -160,13 +160,11 @@ change and whether you need access to a development environment: ## Assign a user to a merge request -When a merge request is created, it's assigned by default to the person who created it. -This person owns the merge request, but isn't responsible for [reviewing it](reviews/index.md). -To assign the merge request to someone else, use the `/assign @user` +To assign the merge request to a user, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area in a merge request, or: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit**. @@ -186,7 +184,7 @@ accountable for it: To assign multiple assignees to a merge request, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area, or: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit** and, from the dropdown list, select all users you want diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 6bfef6ab134..6242a77e931 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,141 +1,11 @@ --- -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: reference, concepts +redirect_to: 'dependencies.md' +remove_date: '2022-11-22' --- -# Merge request dependencies **(PREMIUM)** +This document was moved to [another location](dependencies.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in GitLab 12.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in GitLab 12.4. -> - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in GitLab 12.4. - -Merge request dependencies allows a required order of merging -between merge requests to be expressed. If a merge request "depends on" another, -then it cannot be merged until its dependency is itself merged. - -NOTE: -Merge requests dependencies are a **PREMIUM** feature, but this restriction is -only enforced for the dependent merge request. A merge request in a **FREE** -project can be a dependency of a **PREMIUM** merge request, but not -the other way around. - -## Use cases - -- Ensure changes to a library are merged before changes to a project that - imports the library. -- Prevent a documentation-only merge request from being merged before the merge request - implementing the feature to be documented. -- Require a merge request updating a permissions matrix to be merged before merging a - merge request from someone who hasn't yet been granted permissions. - -It is common for a single logical change to span several merge requests, spread -out across multiple projects, and the order in which they are merged can be -significant. - -For example, given a project `mycorp/awesome-project` that imports a library -at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also** -require changes to `awesome-lib`, and so necessitate two merge requests. Merging -the `awesome-project` merge request before the `awesome-lib` one would -break the default branch. - -The `awesome-project` merge request could be [marked as **Draft**](drafts.md), -and the reason for the draft stated included in the comments. However, this -requires the state of the `awesome-lib` merge request to be manually -tracked, and doesn't scale well if the `awesome-project` merge request -depends on changes to **several** other projects. - -By making the `awesome-project` merge request depend on the -`awesome-lib` merge request instead, this relationship is -automatically tracked by GitLab, and the draft state can be used to -communicate the readiness of the code in each individual merge request -instead. - -## Configuration - -To continue the above example, you can configure a dependency when creating the -new merge request in `awesome-project` (or by editing it, if it already exists). -The dependency needs to be configured on the **dependent** merge -request. There is a **Merge request dependencies** section in the form: - -![Merge request dependencies form control](img/dependencies_edit_v12_4.png) - -Anyone who can edit a merge request can change the list of dependencies. - -New dependencies can be added by reference, or by URL. To remove a dependency, -press the **X** by its reference. - -As dependencies can be specified across projects, it's possible that someone else -has added a dependency for a merge request in a project you don't have access to. -These are shown as a simple count: - -![Merge request dependencies form control with inaccessible merge requests](img/dependencies_edit_inaccessible_v12_4.png) - -If necessary, you can remove all the dependencies like this by pressing the -**X**, just as you would for a single, visible dependency. - -Once you're finished, press the **Save changes** button to submit the request, -or **Cancel** to return without making any changes. - -The list of configured dependencies, and the status of each one, is shown in the -merge request widget: - -![Dependencies in merge request widget](img/dependencies_view_v12_2.png) - -Until all dependencies have, themselves, been merged, the **Merge** -button is disabled for the dependent merge request. In -particular, note that **closed merge requests** still prevent their -dependents from being merged - it is impossible to automatically -determine whether the dependency expressed by a closed merge request -has been satisfied in some other way or not. - -If a merge request has been closed **and** the dependency is no longer relevant, -it must be removed as a dependency, following the instructions above, before -merge. - -## Limitations - -- API support: [issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551) -- Dependencies are not preserved across project export/import: [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549) -- Complex merge order dependencies are not supported: [issue #11393](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) - -The last item merits a little more explanation. Dependencies between merge -requests can be described as a graph of relationships. The simplest possible -graph has one merge request that depends upon another: - -```mermaid -graph LR; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; -``` - -A more complex (and still supported) graph might have one merge request that -directly depends upon several others: - -```mermaid -graph LR; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; - herfriend/another-lib!1-->mycorp/awesome-project!100; -``` - -Several different merge requests can also directly depend upon the -same merge request: - -```mermaid -graph LR; - herfriend/another-lib!1-->myfriend/awesome-lib!10; - herfriend/another-lib!1-->mycorp/awesome-project!100; -``` - -What is **not** supported is a "deep", or "nested" graph of dependencies. For example: - -```mermaid -graph LR; - herfriend/another-lib!1-->myfriend/awesome-lib!10; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; -``` - -In this example, `myfriend/awesome-lib!10` depends on `herfriend/another-lib!1`, -and is itself a dependent of `mycorp/awesome-project!100`. This means that -`myfriend/awesome-lib!10` becomes an **indirect** dependency of -`mycorp/awesome-project!100`, which is not yet supported. + + + + diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 9182cf11566..57c4ff455cb 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -7,125 +7,143 @@ type: reference, concepts # Merge when pipeline succeeds **(FREE)** -When reviewing a merge request that looks ready to merge but still has a -pipeline running, you can set it to merge automatically when the -pipeline succeeds. This way, you don't have to wait for the pipeline to -finish and remember to merge the request manually. +If you review a merge request and it's ready to merge, but the pipeline hasn't +completed yet, you can set it to merge when the pipeline succeeds (MWPS). You don't +have to remember later to merge the work manually: -![Enable](img/merge_when_pipeline_succeeds_enable.png) +![Enable MWPS on a merge request](img/mwps_v15_4.png) -## How it works +If the pipeline succeeds, the merge request is merged. If the pipeline fails, the +author can either retry any failed jobs, or push new commits to fix the failure: -When you select "Merge When Pipeline Succeeds", the status of the merge -request is updated to show the impending merge. If you can't wait -for the pipeline to succeed, you can choose **Merge immediately** -in the dropdown menu on the right of the main button. +- If a retried job succeeds on the second try, the merge request is merged. +- If new commits are added to the merge request, GitLab cancels the MWPS request + to ensure the new changes are reviewed before merge. -The author of the merge request and project members with the Developer role can -cancel the automatic merge at any time before the pipeline finishes. +## Set a merge request to MWPS -![Status](img/merge_when_pipeline_succeeds_status.png) +Prerequisites: -When the pipeline succeeds, the merge request is automatically merged. -When the pipeline fails, the author gets a chance to retry any failed jobs, -or to push new commits to fix the failure. +- You must have at least the Developer role in the project. +- If the project is configured to require it, all threads in the + merge request [must be resolved](../../discussions/index.md#resolve-a-thread). +- The merge request must have received all required approvals. -When the jobs are retried and succeed on the second try, the merge request -is automatically merged. When the merge request is updated with -new commits, the automatic merge is canceled to allow the new -changes to be reviewed. +To do this when pushing from the command line, use the `merge_request.merge_when_pipeline_succeeds` +[push option](../push_options.md). -By default, all threads must be resolved before you see the **Merge when -pipeline succeeds** button. If someone adds a new comment after -the button is selected, but before the jobs in the CI pipeline are -complete, the merge is blocked until you resolve all existing threads. +To do this from the GitLab user interface: -## Only allow merge requests to be merged if the pipeline succeeds +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. +1. Scroll to the merge request reports section. +1. Optional. Select your desired merge options, such as **Delete source branch**, + **Squash commits**, or **Edit commit message**. +1. Select **Merge when pipeline succeeds**. -You can prevent merge requests from being merged if: +If a new comment is added to the merge request after you select **Merge when pipeline succeeds**, +but before the pipeline completes, GitLab blocks the merge until you +resolve all existing threads. -- No pipeline ran. -- The pipeline did not succeed. +## Cancel an auto-merge -This works for both: +If a merge request is set to MWPS, you can cancel it. -- GitLab CI/CD pipelines -- Pipelines run from an [external CI integration](../integrations/index.md#available-integrations) +Prerequisites: + +- You must either be the author of the merge request, or a project member with + at least the Developer role. +- The merge request's pipeline must still be in progress. + +To do this: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. +1. Scroll to the merge request reports section. +1. Select **Cancel auto-merge**. + +![Status](img/cancel-mwps_v15_4.png) + +## Require a successful pipeline for merge + +You can configure your project to require a complete and successful pipeline before +merge. This configuration works for both: + +- GitLab CI/CD pipelines. +- Pipelines run from an [external CI integration](../integrations/index.md#available-integrations). As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md) -does not disable this feature, as it is possible to use pipelines from external -CI providers with this feature. To enable it, you must: +does not disable this feature, but you can use pipelines from external +CI providers with it. + +Prerequisites: + +- Ensure CI/CD is configured to run a pipeline for every merge request. +- You must have at least the Maintainer role in the project. + +To enable this setting: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Scroll to **Merge checks**, and select **Pipelines must succeed**. + This setting also prevents merge requests from being merged if there is no pipeline, + which can [conflict with some rules](#merge-requests-dont-merge-when-successful-pipeline-is-required). +1. Select **Save**. + +### Allow merge after skipped pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. + +When the **Pipelines must succeed** checkbox is checked, +[skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent +merge requests from being merged. + +Prerequisite: -1. On the top bar, select **Menu > Projects** and find your project. +- You must have at least the Maintainer role in the project. + +To change this behavior: + +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Merge requests**. -1. Under **Merge checks**, select the **Pipelines must succeed** checkbox. +1. Under **Merge checks**: + - Select **Pipelines must succeed**. + - Select **Skipped pipelines are considered successful**. 1. Select **Save**. -This setting also prevents merge requests from being merged if there is no pipeline. -You should be careful to configure CI/CD so that pipelines run for every merge request. +## Troubleshooting -### Limitations +### Merge requests don't merge when successful pipeline is required -When this setting is enabled, a merge request is prevented from being merged if there -is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/index.md#only--except) -or [`rules`](../../../ci/yaml/index.md#rules) are used and they don't generate any pipelines. +If you require a successful pipeline for a merge, this setting can conflict with some +use cases that do not generate pipelines, such as [`only/except`](../../../ci/yaml/index.md#only--except) +or [`rules`](../../../ci/yaml/index.md#rules). Ensure your project +[runs a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) for +every merge request, and that the pipeline is successful. -You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) -and that it's successful. +### Ensure test parity between pipeline types -If both a branch pipeline and a merge request pipeline are triggered for a single -merge request, only the success or failure of the *merge request pipeline* is checked. -If the merge request pipeline is configured with fewer jobs than the branch pipeline, -it could allow code that fails tests to be merged: +If a merge request triggers both a branch pipeline and a merge request pipeline, +the success or failure of only the *merge request pipeline* is checked. +If the merge request pipeline contains fewer jobs than the branch pipeline, +it could allow code that fails tests to be merged, like in this example: ```yaml branch-pipeline-job: rules: - if: $CI_PIPELINE_SOURCE == "push" script: - - echo "Code testing scripts here, for example." + - echo "Testing happens here." merge-request-pipeline-job: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" script: - - echo "No tests run, but this pipeline always succeeds and enables merge." + - echo "No testing happens here. This pipeline always succeeds, and enables merge." - echo true ``` -You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines) -for details on avoiding two pipelines for a single merge request. - -### Skipped pipelines - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. - -When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent -merge requests from being merged. To change this behavior: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. -1. Under **Merge checks**: - - Ensure **Pipelines must succeed** is selected. - - Select the **Skipped pipelines are considered successful** checkbox. -1. Select **Save**. - -## From the command line - -You can use [Push Options](../push_options.md) to enable merge when pipeline succeeds -for a merge request when pushing from the command line. - - +Instead, use branch (`push`) pipelines or merge request pipelines, when possible. +For details on avoiding two pipelines for a single merge request, read the +[`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines). diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index c4e4b40dc48..68dd6477408 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -12,9 +12,8 @@ merge requests are merged into an existing branch. ## Configure a project's merge method -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge method** section, select your desired merge method. 1. Select **Save changes**. @@ -110,7 +109,7 @@ gitGraph ``` This method is equivalent to `git merge --ff ` for regular merges, and to -`git merge -squash ` for squash merges. +`git merge --squash ` for squash merges. When the fast-forward merge ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 8f433c13887..a6e0740ff78 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -6,50 +6,86 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Revert changes **(FREE)** -You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") -by clicking the **Revert** button in merge requests and commit details. +You can revert individual commits or an entire merge request in GitLab. +When you revert a commit in Git, you create a new commit that reverses all actions +taken in the original commit: + +- Lines added in the original commit are removed. +- Lines removed in the original commit are added back. +- Lines modified in the original commit are restored to their previous state. + +Your **revert commit** is still subject to your project's access controls and processes. ## Revert a merge request -NOTE: -The **Revert** button is shown only for projects that use the -merge method "Merge Commit", which can be set under the project's -**Settings > General > Merge request**. [Fast-forward commits](methods/index.md#fast-forward-merge) -can not be reverted by using the merge request view. +After a merge request is merged, you can revert all changes in the merge request. + +Prerequisites: -After the merge request has been merged, use the **Revert** button -to revert the changes introduced by that merge request. +- You must have a role in the project that allows you to edit merge requests, and add + code to the repository. +- Your project must use the [merge method](methods/index.md#fast-forward-merge) **Merge Commit**, + which is set in the project's **Settings > General > Merge request**. You can't revert + fast-forwarded commits from the GitLab UI. -![Revert merge request](img/cherry_pick_changes_mr.png) +To do this: -After you select that button, a modal appears where you can choose to -revert the changes directly into the selected branch or you can opt to -create a new merge request with the revert changes. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and identify your merge request. +1. Scroll to the merge request reports area, and find the report showing when the + merge request was merged. +1. Select **Revert**. +1. In **Revert in branch**, select the branch to revert your changes into. +1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. +1. Select **Revert**. -After the merge request has been reverted, the **Revert** button is no longer available. +The option to **Revert** is no longer shown after a merge request is reverted. ## Revert a commit -You can revert a commit from the commit details page: +You can revert any commit in a repository into either: + +- The current branch. +- A new merge request. + +Prerequisites: + +- You must have a role in the project that allows you to edit merge requests, and add + code to the repository. + +To do this: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. If you know the merge request that contains the commit: + 1. On the left sidebar, select **Merge requests** and identify your merge request. + 1. Select **Commits**, then select the title of the commit you want to revert. GitLab displays the contents of the commit. +1. If you don't know the merge request the commit originated from: + 1. On the left sidebar, select **Repository > Commits**. + 1. Select the title of the commit to display full information about the commit. +1. In the top right corner, select **Options**, then select **Revert**. +1. In **Revert in branch**, select the branch to revert your changes into. +1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. +1. Select **Revert**. + +The option to **Revert** is no longer shown after a commit is reverted. -![Revert commit](img/cherry_pick_changes_commit.png) +### Revert a merge commit to a different parent commit -Similar to reverting a merge request, you can opt to revert the changes -directly into the target branch or create a new merge request to revert the -changes. +When you revert a merge commit, the branch you merged to (usually `main`) is always the +first parent. To revert a merge commit to a different parent, +you must revert the commit from the command line: -After a commit is reverted, the **Revert** button is no longer available. +1. Identify the SHA of the parent commit you want to revert to. +1. Identify the parent number of the commit you want to revert to. (Defaults to 1, for the first parent.) +1. Modify this command, replacing `2` with the parent number, and `7a39eb0` with the commit SHA: -When reverting merge commits, the mainline is always the -first parent. If you want to use a different mainline, you need to do that -from the command line. + ```shell + git revert -m 2 7a39eb0 + ``` -Here's an example to revert a merge commit using the second parent as the -mainline: +## Related topics -```shell -git revert -m 2 7a39eb0 -``` +- [Official `git revert` documentation](https://git-scm.com/docs/git-revert)