Add latest changes from gitlab-org/gitlab@master

1 files changed, 148 insertions, 226 deletions

diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md
index 76c348eb93e..fa294b82fef 100644
--- a/doc/user/project/merge_requests/merge_request_approvals.md
+++ b/doc/user/project/merge_requests/merge_request_approvals.md
@@ -7,101 +7,37 @@ type: reference, concepts
 > Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/blog/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only).
 
 Merge request approvals enable enforced code review by requiring specified people
-to approve a merge request before it can be unblocked for merging.
+to approve a merge request before it can be merged.
 
-## Use cases
+Merge request approvals enable multiple use cases:
 
-1. Enforcing review of all code that gets merged into a repository.
-1. Specifying code maintainers for an entire repository.
-1. Specifying reviewers for a given proposed code change.
-1. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes.
+- Enforcing review of all code that gets merged into a repository.
+- Specifying reviewers for a given proposed code change, as well as a minimum number
+  of reviewers, through [Approval rules](#approval-rules)
+- Specifying categories of reviewers, such as backend, frontend, quality assurance,
+  database, etc., for all proposed code changes.
+- Automatically designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers),
+  determined by the files changed in a merge request.
+- [Requiring approval from a security team](#security-approvals-in-merge-requests-ultimate)
+  before merging code that could introduce a vulnerability.**(ULTIMATE)**
 
-## Enabling the new approvals interface
-
-NOTE: **Note:**
-Prior to 12.0, if you are running a self-managed instance, the new interface shown on
-this page will not be available unless the feature flag
-`approval_rules` is enabled, which can be done from the Rails console by
-instance administrators.
-
-Use these commands to start the Rails console:
-
-```sh
-# Omnibus GitLab
-gitlab-rails console
-
-# Installation from source
-cd /home/git/gitlab
-sudo -u git -H bin/rails console RAILS_ENV=production
-```
-
-Then run `Feature.enable(:approval_rules)` to enable the feature flag.
-
-## Editing approvals
-
-To edit the merge request approvals:
-
-1. Navigate to your project's **Settings > General** and expand
-   **Merge request approvals**.
-
-   ![Approvals starter project empty](img/approvals_starter_project_empty.png)
-
-1. Click **Edit**.
-1. Search for users or groups that will be [eligible to approve](#eligible-approvers)
-   merge requests and click the **Add** button to add them as approvers. Note: selecting
-   approvers is optional.
-1. Set the minimum number of required approvals under the **No. approvals required**
-   box. Note: the minimum can be 0.
-1. Click **Update approvers**.
-
-   ![Approvals starter project edit](img/approvals_starter_project_edit.png)
-
-The steps above are the minimum required to get approvals working in your
-merge requests, but there are a couple more options available that might be
-suitable to your workflow:
+## Approval rules
 
-- Choose whether the default settings can be
-  [overridden per merge request](#overriding-the-merge-request-approvals-default-settings)
-- Choose whether [approvals will be reset with new pushed commits](#resetting-approvals-on-push)
+Approval rules define how many approvals a merge request must receive before it can
+be merged, and optionally which users should do the approving. This can be defined:
 
-## Editing approvals **(PREMIUM)**
+- [As project defaults](#adding--editing-a-default-approval-rule)
+- [Per merge request](#editing--overriding-approval-rules-per-merge-request)
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
-
-For GitLab Premium, [multiple approver rules](#multiple-approval-rules-premium) can be configured. To configure the merge
-request approval rules:
-
-1. Navigate to your project's **Settings > General** and expand **Merge request approvals**.
-1. Click **Add approvers** to create a new approval rule.
-1. Just like in [GitLab Starter](#editing-approvals), select the approval members and approvals required.
-1. Give the approval rule a name that describes the set of approvers selected.
-1. Click **Add approval rule** to submit the new rule.
-
-   ![Approvals premium project edit](img/approvals_premium_project_edit_v12_5.png)
-
-## Multiple approval rules **(PREMIUM)**
+If no approval rules are defined, any user can approve a merge request, though the default
+minimum number of required approvers can still be set in the [project settings for merge request approvals](#merge-request-approvals-project-settings).
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
-
-For GitLab Premium, a merge request's overall approval status is determined by a set of rules. Each rule contains:
-
-- A set of [eligible approvers](#eligible-approvers).
-- A minimum number of approvals required.
-
-When an [eligible approver](#eligible-approvers) approves a merge request, it will reduce the number of approvals left for
-all rules that the approver belongs to.
-
-![Approvals premium merge request widget](img/approvals_premium_mr_widget.png)
-
-If no approval rules are set, then the overall minimum number of approvals required can be configured. With no approval rules,
-any [eligible approver](#eligible-approvers) may approve.
-
-## Eligible approvers
+### Eligible approvers
 
 The following can approve merge requests:
 
 - Users being added as approvers at project or merge request level.
-- [Code owners](#code-owners-as-eligible-approvers-starter) to the files changed by the merge request.
+- [Code owners](#code-owners-as-eligible-approvers) to the files changed by the merge request.
 
 An individual user can be added as an approver for a project if they are a member of:
 
@@ -109,8 +45,8 @@ An individual user can be added as an approver for a project if they are a membe
 - The project's immediate parent group.
 - A group that has access to the project via a [share](../members/share_project_with_groups.md).
 
-A group can also be added as an approver. [In the future](https://gitlab.com/gitlab-org/gitlab/issues/2048),
-group approvers will be restricted.
+A group of users can also be added as approvers. In the future, group approvers may be
+[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/issues/2048).
 
 If a user is added as an individual approver and is also part of a group approver,
 then that user is just counted once. The merge request author, as well as users who have committed
@@ -119,19 +55,25 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei
 and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default)
 are enabled on the project settings.
 
-### Code Owners as eligible approvers **(STARTER)**
+#### Implicit approvers
+
+If the number of required approvals is greater than the number of assigned approvers,
+approvals from other users will count towards meeting the requirement. These would be
+users with developer [permissions](../../permissions.md) or higher in the project who
+were not explicitly listed in the approval rules.
+
+#### Code Owners as eligible approvers
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5.
 
-Once you've added [Code Owners](../code_owners.md) to your
-repository, the owners to the corresponding files will become
-eligible approvers, together with members with Developer or
-higher permissions.
+If you add [Code Owners](../code_owners.md) to your repository, the owners to the
+corresponding files will become eligible approvers, together with members with Developer
+or higher permissions.
 
 To enable this merge request approval rule:
 
 1. Navigate to your project's **Settings > General** and expand
-**Merge request approvals**.
+   **Merge request approvals**.
 1. Locate **All members with Developer role or higher and code owners (if any)** and click **Edit** to choose the number of approvals required.
 
 ![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v12_4.png)
@@ -144,205 +86,185 @@ indistinguishably.
 Alternatively, you can **require**
 [Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
 
-### Implicit approvers
+### Adding / editing a default approval rule
 
-If the number of required approvals is greater than the number of approvers,
-other users will become implicit approvers to fill the gap.
-Those implicit approvers include members of the given project with Developer role or higher.
+To add or edit the default merge request approval rule:
 
-## Adding or removing an approval
+1. Navigate to your project's **Settings > General** and expand **Merge request approvals**.
 
-If approvals are activated for the given project, when a user visits an open
-merge request, depending on their [eligibility](#eligible-approvers), one of
-the following is possible:
+1. Click **Add approval rule**, or **Edit**.
+   - Add or change the **Rule name**.
+   - Set the number of required approvals in **No. approvals required**. The minimum value is `0`.
+   - (Optional) Search for users or groups that will be [eligible to approve](#eligible-approvers)
+     merge requests and click the **Add** button to add them as approvers. Before typing
+     in the search field, approvers will be suggested based on the previous authors of
+     the files being changed by the merge request.
+   - (Optional) Click the **"trashcan"** button next to a group or user to delete it from
+     the rule.
+1. Click **Add approval rule** or **Update approval rule**.
 
-- **They are not an eligible approver**: They cannot do anything with respect
-  to approving this merge request.
+Any merge requests that were created before changing the rules will not be changed.
+They will keep the original approval rules, unless manually [overridden](#editing--overriding-approval-rules-per-merge-request).
 
-- **They have not approved this merge request**:
+NOTE: **Note:**
+If a merge request targets a different project, such as from a fork to the upstream project,
+the default approval rules will be taken from the target (upstream) project, not the
+source (fork).
 
-  - If the required number of approvals has _not_ been yet met, they can approve
-    it by clicking the displayed **Approve** button.
+#### Editing / overriding approval rules per merge request
 
-    ![Approve](img/approve.png)
+> Introduced in GitLab Enterprise Edition 9.4.
 
-  - If the required number of approvals has already been met, they can still
-    approve it by clicking the displayed **Approve additionally** button.
+By default, the merge request approval rule listed in each merge request (MR) can be
+edited by the MR author or a user with sufficient [permissions](../../permissions.md).
+This ability can be disabled in the [merge request approvals settings](#prevent-overriding-default-approvals).
 
-    ![Add approval](img/approve_additionally.png)
+One possible scenario would be to add more approvers than were defined in the default
+settings.
 
-- **They have already approved this merge request**: They can remove their approval.
+When creating or editing a merge request, find the **Approval rules** section, then follow
+the same steps as [Adding / editing a default approval rule](#adding--editing-a-default-approval-rule).
 
-  ![Remove approval](img/remove_approval.png)
+### Multiple approval rules **(PREMIUM)**
 
-NOTE: **Note:**
-The merge request author is only allowed to approve their own merge request
-if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is disabled on the project settings.
-
-For a given merge request, if the approval restrictions have been satisfied,
-the merge request is unblocked and can be merged.
-Note that meeting the required number of approvals is a necessary, but not
-sufficient condition for unblocking a merge request from being merged. There
-are other conditions that may block it, such as merge conflicts,
-[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved)
-or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md).
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
 
-## Overriding the merge request approvals default settings
+In GitLab Premium, it is possible to have multiple approval rules per merge request,
+as well as multiple default approval rules per project.
 
-> Introduced in GitLab Enterprise Edition 9.4.
+Adding or editing multiple default rules is identical to
+[adding or editing a single default approval rule](#adding--editing-a-default-approval-rule),
+except the **Add approval rule** button will be available to add more rules, even after
+a rule is already defined.
 
-NOTE: **Note:**
-If you are using GitLab Premium, things are a little different with [multiple approval rules](#multiple-approval-rules-premium).
-Read the differences [in GitLab Premium when overriding merge request approvals](#overriding-merge-request-approvals-default-settings-premium).
+Similarly, editing or overriding multiple approval rules per merge request is identical
+to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request),
+except the **Add approval rule** button will be available to add more rules, even after
+a rule is already defined.
+
+When an [eligible approver](#eligible-approvers) approves a merge request, it will
+reduce the number of approvals left for all rules that the approver belongs to.
 
-If approvals are [set at the project level](#editing-approvals), the
-default configuration (number of required approvals and approvers) can be
-overridden for each merge request in that project.
+![Approvals premium merge request widget](img/approvals_premium_mr_widget.png)
 
-One possible scenario would be to assign a group of approvers at the project
-level and change them later when creating or editing the merge request.
+## Adding or removing an approval
 
-First, you have to enable this option in the project's settings:
+When an [eligible approver](#eligible-approvers) visits an open merge request,
+one of the following is possible:
 
-1. Navigate to your project's **Settings > General** and expand
-   **Merge request approvals**
-1. Tick the "Can override approvers and approvals required per merge request"
-   checkbox
+- If the required number of approvals has _not_ been yet met, they can approve
+  it by clicking the displayed **Approve** button.
 
-   ![Approvals can override](img/approvals_can_override.png)
+  ![Approve](img/approve.png)
 
-1. Click **Save changes**
+- If the required number of approvals has already been met, they can still
+  approve it by clicking the displayed **Approve additionally** button.
 
-NOTE: **Note:**
-If approver overriding is enabled
-and the project level approvers are changed after a merge request is created,
-the merge request retains the previous approvers.
-However, the approvers can be changed by [editing the merge request](#overriding-the-merge-request-approvals-default-settings).
-
-The default approval settings can now be overridden when creating a
-[merge request](index.md) or by editing it after it's been created:
-
-1. Click **Edit** under the **Approvers** section.
-1. Search for users or groups that will be [eligible to approve](#eligible-approvers)
-   merge requests and click the **Add** button to add them as approvers or
-   remove existing approvers that were set in the project's settings.
-1. If you want to change the number of required approvals, set a new number
-   in the **No. approvals required** box.
-1. Click **Update approvers**.
+  ![Add approval](img/approve_additionally.png)
+
+- **They have already approved this merge request**: They can remove their approval.
+
+  ![Remove approval](img/remove_approval.png)
 
 NOTE: **Note:**
-If you are contributing to a forked project, things are a little different.
-Read what happens  when the
-[source and target branches are not the same](#merge-requests-with-different-source-branch-and-target-branch-projects).
+The merge request author is not allowed to approve their own merge request if
+[**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests)
+is enabled in the project settings.
 
-## Overriding merge request approvals default settings **(PREMIUM)**
+Once the approval rules have been met, the merge request can be merged if there is nothing
+else blocking it. Note that the merge request could still be blocked by other conditions,
+such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved),
+or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md).
 
-In GitLab Premium, when the approval rules are [set at the project level](#editing-approvals-premium),
-and **Can override approvers and approvals required per merge request** is checked,
-approval rules can be added to an MR with no restriction.
+## Merge request approvals project settings
 
-## Resetting approvals on push
+The project settings for Merge request approvals are found by going to
+**Settings > General** and expanding **Merge request approvals**.
 
-If approvals are [set at the project level](#editing-approvals),
-you can choose whether all approvals on a merge request are removed when
-new commits are pushed to the source branch of the merge request:
+### Prevent overriding default approvals
 
-1. Navigate to your project's **Settings > General** and expand
-   **Merge request approvals**
-1. Tick the "Remove all approvals in a merge request when new commits are pushed to its source branch"
-   checkbox
+By default, users are able to edit the approval rules in merge requests. If disabled,
+the approval rules for all new merge requests will be determined by the
+[default approval rules](#adding--editing-a-default-approval-rule). To disable this feature:
 
-   ![Approvals remove on push](img/approvals_remove_on_push.png)
+1. Uncheck the **Can override approvers and approvals required per merge request** checkbox.
+1. Click **Save changes**
 
+### Resetting approvals on push
+
+You can force all approvals on a merge request to be removed when new commits are
+pushed to the source branch of the merge request. If disabled, approvals will persist
+even if there are changes added to the merge request. To enable this feature:
+
+1. Check the **Remove all approvals in a merge request when new commits are pushed to its source branch**
+   checkbox.
 1. Click **Save changes**
 
 NOTE: **Note:**
 Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md)
-from the UI.
-However, approvals will be reset if the target branch is changed.
-
-If you want approvals to persist, independent of changes to the merge request,
-turn this setting to off by unchecking the box and saving the changes.
+from the UI. However, approvals will be reset if the target branch is changed.
 
-## Allowing merge request authors to approve their own merge requests
+### Allowing merge request authors to approve their own merge requests
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
 
-You can allow merge request authors to self-approve merge requests by
-enabling it [at the project level](#editing-approvals). Authors
+You can allow merge request authors to self-approve merge requests. Authors
 also need to be included in the approvers list in order to be able to
-approve their merge request.
+approve their merge request. To enable this feature:
 
-1. Navigate to your project's **Settings > General** and expand **Merge request approvals**.
-1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox, which is enabled by default.
+1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox,
+   which is enabled by default.
 1. Click **Save changes**.
 
-## Prevent approval of merge requests by their committers
+### Prevent approval of merge requests by their committers
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10.
 
-You can prevent users that have committed to a merge request from approving it by
-enabling [**Prevent approval of merge requests by their committers**](#prevent-approval-of-merge-requests-by-their-committers).
+You can prevent users that have committed to a merge request from approving it. To
+enable this feature:
 
-1. Navigate to your project's **Settings > General** and expand **Merge request approvals**.
-1. Tick the checkbox **Prevent approval of merge requests by their committers**.
+1. Check the **Prevent approval of merge requests by their committers** checkbox.
 1. Click **Save changes**.
 
-## Require authentication when approving a merge request **(STARTER)**
+### Require authentication when approving a merge request
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0.
 
-You can force the approver to enter a password in order to authenticate who is approving the merge request by
-enabling **Require user password to approve**. This enables an Electronic Signature
-for approvals such as the one defined by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)):
+You can force the approver to enter a password in order to authenticate before adding
+the approval. This enables an Electronic Signature for approvals such as the one defined
+by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)).
+To enable this feature:
 
-1. Navigate to your project's **Settings > General** and expand **Merge request approvals**.
-1. Tick the checkbox **Require user password to approve**.
+1. Check the **Require user password to approve** checkbox.
 1. Click **Save changes**.
 
-## Merge requests with different source branch and target branch projects
-
-If the merge request source branch and target branch belong to different
-projects (which happens in merge requests in forked projects), everything is
-with respect to the target branch's project (typically the original project).
-In particular, since the merge request in this case is part of the target
-branch's project, the relevant settings are the target project's. The source
-branch's project settings are not applicable. Even if you start the merge
-request from the source branch's project UI, pay attention to the created merge
-request itself. It belongs to the target branch's project.
-
-## Approver suggestions
-
-Approvers are suggested for merge requests based on the previous authors of the files affected by the merge request.
-
-## Filtering merge requests by approvers
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/9468) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.9.
-
-To filter merge requests by an individual approver, you can type (or select from
-the dropdown) `approver` and select the user.
-
-![Filter MRs by an approver](img/filter_approver_merge_requests.png)
-
 ## Security approvals in merge requests **(ULTIMATE)**
 
-> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2.
-
 Merge Request Approvals can be configured to require approval from a member
 of your security team when a vulnerability would be introduced by a merge request.
 
 For more information, see
-[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests-ultimate).
+[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests).
+
+## Enabling the new approvals interface
 
-## License compliance approvals in merge requests **(ULTIMATE)**
+Since [GitLab v12.0](https://gitlab.com/gitlab-org/gitlab/issues/10685), an updated approvals
+interface is available by default. In versions older than 12.0, the updated interface is not
+available unless the `approval_rules` feature flag is enabled, which can be done from
+the Rails console by instance administrators.
 
-> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3.
+Use these commands to start the Rails console:
 
-Merge Request Approvals can be configured to require approval from a member
-of your security team when a blacklisted software license would be introduced by a merge request.
+```shell
+# Omnibus GitLab
+gitlab-rails console
 
-For more information, see
-[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests-ultimate).
+# Installation from source
+cd /home/git/gitlab
+sudo -u git -H bin/rails console RAILS_ENV=production
+```
+
+Then run `Feature.enable(:approval_rules)` to enable the updated interface.
 
 <!-- ## Troubleshooting