Merge branch 'docs-mr-approvals' into 'master'

MR Approvals documentation Revamp

See merge request gitlab-org/gitlab!23861

doc/api/merge_request_approvals.md

@@ -956,7 +956,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve
 | `id`                | integer | yes      | The ID of a project     |
 | `merge_request_iid` | integer | yes      | The IID of MR           |
 | `sha`               | string  | no       | The HEAD of the MR      |
-| `approval_password` **(STARTER)** | string  | no      | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request-starter) is enabled in the project settings. |
+| `approval_password` **(STARTER)** | string  | no      | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request) is enabled in the project settings. |
 
 The `sha` parameter works in the same way as
 when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must

doc/user/application_security/index.md

@@ -148,12 +148,15 @@ Clicking on this button will create a merge request to apply the solution onto t
 
 ![Create merge request from vulnerability](img/create_issue_with_list_hover.png)
 
-## Security approvals in merge requests **(ULTIMATE)**
+## Security approvals in merge requests
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9928) 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, or a software license compliance violation would be introduced by a merge request.
+Merge Request Approvals can be configured to require approval from a member of your
+security team when a merge request would introduce one of the following security issues:
+
+- a security vulnerability
+- a software license compliance violation
 
 This threshold is defined as `high`, `critical`, or `unknown`
 severity. When any vulnerabilities are present within a merge request, an

doc/user/project/code_owners.md

@@ -33,7 +33,7 @@ the given file.
 Once you've set Code Owners to a project, you can configure it to
 receive approvals:
 
-- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers-starter). **(STARTER)**
+- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers).
 - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
 
 Once set, Code Owners are displayed in merge requests widgets:

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
 

doc/user/search/index.md

@@ -73,6 +73,15 @@ You can filter issues and merge requests by specific terms included in titles or
 
 ![filter issues by specific terms](img/issue_search_by_term.png)
 
+### Filtering merge requests by approvers **(STARTER)**
+
+> [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)
+
 ## Search history
 
 You can view recent searches by clicking on the little arrow-clock icon, which is to the left of the search input. Click the search entry to run that search again. This feature is available for issues and merge requests. Searches are stored locally in your browser.