Add latest changes from gitlab-org/gitlab@master

19 files changed, 425 insertions, 398 deletions

diff --git a/doc/README.md b/doc/README.md
index 1cc309bd957..a56f17e3bf0 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -110,7 +110,7 @@ There are many ways to integrate with GitLab, including:
 |:-------------------------------------------|:------------|
 | [GitLab REST API](api/README.md)           | Integrate with GitLab using our REST API. |
 | [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. |
-| [Integrations](integration/README.md)      | Integrations with third-party products. |
+| [Integrations](integration/index.md)      | Integrations with third-party products. |
 
 ## Contributing to GitLab
 
diff --git a/doc/administration/consul.md b/doc/administration/consul.md
index 926267a414a..a748259aff0 100644
--- a/doc/administration/consul.md
+++ b/doc/administration/consul.md
@@ -83,7 +83,7 @@ curl "http://127.0.0.1:8500/v1/health/state/critical"
 Consul nodes communicate using the raft protocol. If the current leader goes
 offline, there needs to be a leader election. A leader node must exist to facilitate
 synchronization across the cluster. If too many nodes go offline at the same time,
-the cluster will lose quorum and not elect a leader due to
+the cluster loses quorum and doesn't elect a leader due to
 [broken consensus](https://www.consul.io/docs/architecture/consensus).
 
 Consult the [troubleshooting section](#troubleshooting-consul) if the cluster is not
@@ -122,19 +122,19 @@ db-a            XX.XX.X.Y:8301        alive   client  0.9.0  2         gitlab_co
 db-b            XX.XX.X.Y:8301        alive   client  0.9.0  2         gitlab_consul
 ```
 
-Ideally all nodes will have a `Status` of `alive`.
+Ideally all nodes have a `Status` of `alive`.
 
 ### Restart Consul
 
 If it is necessary to restart Consul, it is important to do this in
 a controlled manner to maintain quorum. If quorum is lost, to recover the cluster,
-you will need to follow the Consul [outage recovery](#outage-recovery) process.
+you follow the Consul [outage recovery](#outage-recovery) process.
 
 To be safe, it's recommended that you only restart Consul in one node at a time to
 ensure the cluster remains intact. For larger clusters, it is possible to restart
 multiple nodes at a time. See the
 [Consul consensus document](https://www.consul.io/docs/architecture/consensus#deployment-table)
-for how many failures it can tolerate. This will be the number of simultaneous
+for the number of failures it can tolerate. This will be the number of simultaneous
 restarts it can sustain.
 
 To restart Consul:
@@ -145,13 +145,13 @@ sudo gitlab-ctl restart consul
 
 ### Consul nodes unable to communicate
 
-By default, Consul will attempt to
+By default, Consul attempts to
 [bind](https://www.consul.io/docs/agent/options#_bind) to `0.0.0.0`, but
-it will advertise the first private IP address on the node for other Consul nodes
+it advertises the first private IP address on the node for other Consul nodes
 to communicate with it. If the other nodes cannot communicate with a node on
-this address, then the cluster will have a failed status.
+this address, then the cluster has a failed status.
 
-If you are running into this issue, you will see messages like the following in `gitlab-ctl tail consul` output:
+If you run into this issue, then messages like the following are output in `gitlab-ctl tail consul`:
 
 ```plaintext
 2017-09-25_19:53:39.90821     2017/09/25 19:53:39 [WARN] raft: no known peers, aborting election
@@ -181,10 +181,10 @@ If you still see the errors, you may have to
 
 ### Consul does not start - multiple private IPs
 
-In case that a node has multiple private IPs, Consul will be confused as to
-which of the private addresses to advertise, and then immediately exit on start.
+If a node has multiple private IPs, Consul doesn't know about
+which of the private addresses to advertise, and then it immediately exits on start.
 
-You will see messages like the following in `gitlab-ctl tail consul` output:
+Messages like the following are output in `gitlab-ctl tail consul`:
 
 ```plaintext
 2017-11-09_17:41:45.52876 ==> Starting Consul agent...
@@ -211,8 +211,8 @@ To fix this:
 
 ### Outage recovery
 
-If you lost enough Consul nodes in the cluster to break quorum, then the cluster
-is considered failed, and it will not function without manual intervention.
+If you have lost enough Consul nodes in the cluster to break quorum, then the cluster
+is considered to have failed and cannot function without manual intervention.
 In that case, you can either recreate the nodes from scratch or attempt a
 recover.
 
diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md
index f1884f297e8..8026842248d 100644
--- a/doc/administration/geo/index.md
+++ b/doc/administration/geo/index.md
@@ -27,7 +27,7 @@ to clone and fetch large repositories, speeding up development.
 
 For a video introduction to Geo, see [Introduction to GitLab Geo - GitLab Features](https://www.youtube.com/watch?v=-HDLxSjEh6w).
 
-To make sure you're using the right version of the documentation, navigate to [the source version of this page on GitLab.com](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/administration/geo/index.md) and choose the appropriate release from the **Switch branch/tag** dropdown. For example, [`v11.2.3-ee`](https://gitlab.com/gitlab-org/gitlab/blob/v11.2.3-ee/doc/administration/geo/index.md).
+To make sure you're using the right version of the documentation, navigate to [this page on GitLab.com](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/administration/geo/index.md) and choose the appropriate release from the **Switch branch/tag** dropdown. For example, [`v11.2.3-ee`](https://gitlab.com/gitlab-org/gitlab/blob/v11.2.3-ee/doc/administration/geo/index.md).
 
 ## Use cases
 
diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md
index 272b746015b..014ca59e571 100644
--- a/doc/administration/geo/replication/location_aware_git_url.md
+++ b/doc/administration/geo/replication/location_aware_git_url.md
@@ -8,11 +8,11 @@ type: howto
 # Location-aware Git remote URL with AWS Route53 **(PREMIUM SELF)**
 
 You can provide GitLab users with a single remote URL that automatically uses
-the Geo node closest to them. This means users don't need to update their Git
-configuration to take advantage of closer Geo nodes as they move.
+the Geo site closest to them. This means users don't need to update their Git
+configuration to take advantage of closer Geo sites as they move.
 
 This is possible because, Git push requests can be automatically redirected
-(HTTP) or proxied (SSH) from **secondary** nodes to the **primary** node.
+(HTTP) or proxied (SSH) from **secondary** sites to the **primary** site.
 
 Though these instructions use [AWS Route53](https://aws.amazon.com/route53/),
 other services such as [Cloudflare](https://www.cloudflare.com/) could be used
@@ -20,30 +20,30 @@ as well.
 
 NOTE:
 You can also use a load balancer to distribute web UI or API traffic to
-[multiple Geo **secondary** nodes](../../../user/admin_area/geo_nodes.md#multiple-secondary-nodes-behind-a-load-balancer).
-Importantly, the **primary** node cannot yet be included. See the feature request
+[multiple Geo **secondary** sites](../../../user/admin_area/geo_nodes.md#multiple-secondary-nodes-behind-a-load-balancer).
+Importantly, the **primary** site cannot yet be included. See the feature request
 [Support putting the **primary** behind a Geo node load balancer](https://gitlab.com/gitlab-org/gitlab/-/issues/10888).
 
 ## Prerequisites
 
 In this example, we have already set up:
 
-- `primary.example.com` as a Geo **primary** node.
-- `secondary.example.com` as a Geo **secondary** node.
+- `primary.example.com` as a Geo **primary** site.
+- `secondary.example.com` as a Geo **secondary** site.
 
 We will create a `git.example.com` subdomain that will automatically direct
 requests:
 
-- From Europe to the **secondary** node.
-- From all other locations to the **primary** node.
+- From Europe to the **secondary** site.
+- From all other locations to the **primary** site.
 
 In any case, you require:
 
-- A working GitLab **primary** node that is accessible at its own address.
-- A working GitLab **secondary** node.
+- A working GitLab **primary** site that is accessible at its own address.
+- A working GitLab **secondary** site.
 - A Route53 Hosted Zone managing your domain.
 
-If you haven't yet set up a Geo _primary_ node and _secondary_ node, see the
+If you haven't yet set up a Geo _primary_ site and _secondary_ site, see the
 [Geo setup instructions](../index.md#setup-instructions).
 
 ## Create a traffic policy
@@ -89,7 +89,7 @@ routing configurations.
    ![Created policy record](img/single_git_created_policy_record.png)
 
 You have successfully set up a single host, e.g. `git.example.com` which
-distributes traffic to your Geo nodes by geolocation!
+distributes traffic to your Geo sites by geolocation!
 
 ## Configure Git clone URLs to use the special Git URL
 
@@ -114,10 +114,10 @@ You can customize the:
 After following the configuration steps above, handling for Git requests is now location aware.
 For requests:
 
-- Outside Europe, all requests are directed to the **primary** node.
+- Outside Europe, all requests are directed to the **primary** site.
 - Within Europe, over:
   - HTTP:
-    - `git clone http://git.example.com/foo/bar.git` is directed to the **secondary** node.
+    - `git clone http://git.example.com/foo/bar.git` is directed to the **secondary** site.
     - `git push` is initially directed to the **secondary**, which automatically
       redirects to `primary.example.com`.
   - SSH:
diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md
index 4fc52995fc1..f4e099c3128 100644
--- a/doc/ci/yaml/script.md
+++ b/doc/ci/yaml/script.md
@@ -86,7 +86,7 @@ Second command line.
 When you omit the `>` or `|` block scalar indicators, GitLab concatenates non-empty
 lines to form the command. Make sure the lines can run when concatenated.
 
-[Shell here documents](https://en.wikipedia.org/wiki/Here_document) work with the
+[These documents](https://en.wikipedia.org/wiki/Here_document) work with the
 `|` and `>` operators as well. The example below transliterates lower case letters
 to upper case:
 
diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md
index 27ba2e79deb..922a0cd46a2 100644
--- a/doc/development/approval_rules.md
+++ b/doc/development/approval_rules.md
@@ -87,7 +87,7 @@ The `ApprovalState` model get these records when approval rules are not
 overwritten.
 
 The `protected_branches` attribute is set and used when a rule is scoped to
-protected branches. See [Scoped to Protected Branch doc](../user/project/merge_requests/approvals/rules.md#scoped-to-protected-branch)
+protected branches. See [Approvals for protected branches](../user/project/merge_requests/approvals/rules.md#approvals-for-protected-branches)
 for more information about the feature.
 
 ### `ApprovalMergeRequestRule`
diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md
index e8c0c751af9..a4ecf216101 100644
--- a/doc/development/go_guide/index.md
+++ b/doc/development/go_guide/index.md
@@ -449,12 +449,12 @@ Once you've picked a new Go version to use, the steps to update Omnibus and CNG
 are:
 
 - [Create a merge request in the CNG project](https://gitlab.com/gitlab-org/build/CNG/-/edit/master/ci_files/variables.yml?branch_name=update-go-version),
-  updating the `GO_VERSION` in `ci_files/variables.yml`.
+  update the `GO_VERSION` in `ci_files/variables.yml`.
 - [Create a merge request in the `gitlab-omnibus-builder` project](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/edit/master/docker/VERSIONS?branch_name=update-go-version),
-  updating the `GO_VERSION` in `docker/VERSIONS`.
+  update the `GO_VERSION` in `docker/VERSIONS`.
 - Tag a new release of `gitlab-omnibus-builder` containing the change.
 - [Create a merge request in the `omnibus-gitlab` project](https://gitlab.com/gitlab-org/omnibus-gitlab/edit/master/.gitlab-ci.yml?branch_name=update-gitlab-omnibus-builder-version),
-  updating the `BUILDER_IMAGE_REVISION` to match the newly-created tag.
+  update the `BUILDER_IMAGE_REVISION` to match the newly-created tag.
 
 To reduce unnecessary differences between two distribution methods, Omnibus and
 CNG **should always use the same Go version**.
diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md
index ff831bfa348..8a8026d6e09 100644
--- a/doc/development/multi_version_compatibility.md
+++ b/doc/development/multi_version_compatibility.md
@@ -65,7 +65,7 @@ Let's see how we can handle them safely.
 ### Route changes
 
 When changing routing we should pay attention to make sure a route generated from the new version can be served by the old one and vice versa.
-As you can see in [an example later on this page](#some-links-to-issues-and-mrs-were-broken), not doing it can lead to an outage.
+As you can see in [this page](#some-links-to-issues-and-mrs-were-broken), not doing it can lead to an outage.
 This type of change may look like an immediate switch between the two implementations. However,
 especially with the canary stage, there is an extended period of time where both version of the code
 coexists in production.
diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md
index ae0cbd44629..b4bdd88e654 100644
--- a/doc/development/snowplow/index.md
+++ b/doc/development/snowplow/index.md
@@ -131,8 +131,8 @@ _** Property is usually the best place for variable strings._
 
 ```sql
 SELECT
+  session_id,
   event_id,
-  v_tracker,
   event_label,
   event_action,
   event_property,
diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md
index 06adde16f80..1b232c361ee 100644
--- a/doc/install/google_cloud_platform/index.md
+++ b/doc/install/google_cloud_platform/index.md
@@ -130,7 +130,7 @@ GitLab can be configured to authenticate with other OAuth providers, LDAP, SAML,
 Kerberos, etc. Here are some documents you might be interested in reading:
 
 - [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/)
-- [Integration documentation](../../integration/README.md)
+- [Integration documentation](../../integration/index.md)
 - [GitLab Pages configuration](../../administration/pages/index.md)
 - [GitLab Container Registry configuration](../../administration/packages/container_registry.md)
 
diff --git a/doc/integration/README.md b/doc/integration/README.md
index c725cc08556..c5274535d98 100644
--- a/doc/integration/README.md
+++ b/doc/integration/README.md
@@ -1,105 +1,8 @@
 ---
-stage: Create
-group: Ecosystem
-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
-comments: false
+redirect_to: 'index.md'
 ---
 
-# GitLab integrations **(FREE)**
+This document was moved to [another location](index.md).
 
-GitLab can be integrated with external services for enhanced functionality.
-
-## Issue trackers
-
-You can use an [external issue tracker](external-issue-tracker.md) at the same time as the GitLab
-issue tracker, or use only the external issue tracker.
-
-## Authentication sources
-
-GitLab can be configured to authenticate access requests with the following authentication sources:
-
-- Enable the [Auth0 OmniAuth](auth0.md) provider.
-- Enable sign in with [Bitbucket](bitbucket.md) accounts.
-- Configure GitLab to sign in using [CAS](cas.md).
-- Integrate with [Kerberos](kerberos.md).
-- Enable sign in via [LDAP](../administration/auth/ldap/index.md).
-- Enable [OAuth2 provider](oauth_provider.md) application creation.
-- Use [OmniAuth](omniauth.md) to enable sign in via Twitter, GitHub, GitLab.com, Google,
-  Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure, or Authentiq ID.
-- Use GitLab as an [OpenID Connect](openid_connect_provider.md) identity provider.
-- Authenticate to [Vault](vault.md) through GitLab OpenID Connect.
-- Configure GitLab as a [SAML](saml.md) 2.0 Service Provider.
-
-## Security enhancements
-
-GitLab can be integrated with the following external services to enhance security:
-
-- [Akismet](akismet.md) helps reduce spam.
-- Google [reCAPTCHA](recaptcha.md) helps verify new users.
-
-GitLab also provides features to improve the security of your own application. For more details see [GitLab Secure](../user/application_security/index.md).
-
-## Security partners
-
-GitLab has integrated with several security partners. For more information, see
-[Security partners integration](security_partners/index.md).
-
-## Continuous integration
-
-GitLab can be integrated with the following external service for continuous integration:
-
-- [Jenkins](jenkins.md) CI.
-
-## Feature enhancements
-
-GitLab can be integrated with the following enhancements:
-
-- Add GitLab actions to [Gmail actions buttons](gmail_action_buttons_for_gitlab.md).
-- Configure [PlantUML](../administration/integration/plantuml.md)
-or [Kroki](../administration/integration/kroki.md) to use diagrams in AsciiDoc and Markdown documents.
-- Attach merge requests to [Trello](trello_power_up.md) cards.
-- Enable integrated code intelligence powered by [Sourcegraph](sourcegraph.md).
-- Add [Elasticsearch](elasticsearch.md) for [Advanced Search](../user/search/advanced_search.md).
-
-## Integrations
-
-Integration with services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [Integrations](../user/project/integrations/overview.md).
-
-## Troubleshooting
-
-### SSL certificate errors
-
-When trying to integrate GitLab with services using self-signed certificates,
-SSL certificate errors can occur in different parts of the application. Sidekiq
-is a common culprit.
-
-There are two approaches you can take to solve this:
-
-1. Add the root certificate to the trusted chain of the OS.
-1. If using Omnibus, you can add the certificate to the GitLab trusted certificates.
-
-**OS main trusted chain**
-
-This [resource](https://manuals.gfi.com/en/kerio/connect/content/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html)
-has all the information you need to add a certificate to the main trusted chain.
-
-This [answer](https://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu)
-at Super User also has relevant information.
-
-**Omnibus Trusted Chain**
-
-[Install the self signed certificate or custom certificate authorities](https://docs.gitlab.com/omnibus/common_installation_problems/README.html#using-self-signed-certificate-or-custom-certificate-authorities)
-in to Omnibus GitLab.
-
-It is enough to concatenate the certificate to the main trusted certificate
-however it may be overwritten during upgrades:
-
-```shell
-cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem
-```
-
-After that restart GitLab with:
-
-```shell
-sudo gitlab-ctl restart
-```
+<!-- This redirect file can be deleted after <2021-07-30>. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/integration/index.md b/doc/integration/index.md
new file mode 100644
index 00000000000..c725cc08556
--- /dev/null
+++ b/doc/integration/index.md
@@ -0,0 +1,105 @@
+---
+stage: Create
+group: Ecosystem
+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
+comments: false
+---
+
+# GitLab integrations **(FREE)**
+
+GitLab can be integrated with external services for enhanced functionality.
+
+## Issue trackers
+
+You can use an [external issue tracker](external-issue-tracker.md) at the same time as the GitLab
+issue tracker, or use only the external issue tracker.
+
+## Authentication sources
+
+GitLab can be configured to authenticate access requests with the following authentication sources:
+
+- Enable the [Auth0 OmniAuth](auth0.md) provider.
+- Enable sign in with [Bitbucket](bitbucket.md) accounts.
+- Configure GitLab to sign in using [CAS](cas.md).
+- Integrate with [Kerberos](kerberos.md).
+- Enable sign in via [LDAP](../administration/auth/ldap/index.md).
+- Enable [OAuth2 provider](oauth_provider.md) application creation.
+- Use [OmniAuth](omniauth.md) to enable sign in via Twitter, GitHub, GitLab.com, Google,
+  Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure, or Authentiq ID.
+- Use GitLab as an [OpenID Connect](openid_connect_provider.md) identity provider.
+- Authenticate to [Vault](vault.md) through GitLab OpenID Connect.
+- Configure GitLab as a [SAML](saml.md) 2.0 Service Provider.
+
+## Security enhancements
+
+GitLab can be integrated with the following external services to enhance security:
+
+- [Akismet](akismet.md) helps reduce spam.
+- Google [reCAPTCHA](recaptcha.md) helps verify new users.
+
+GitLab also provides features to improve the security of your own application. For more details see [GitLab Secure](../user/application_security/index.md).
+
+## Security partners
+
+GitLab has integrated with several security partners. For more information, see
+[Security partners integration](security_partners/index.md).
+
+## Continuous integration
+
+GitLab can be integrated with the following external service for continuous integration:
+
+- [Jenkins](jenkins.md) CI.
+
+## Feature enhancements
+
+GitLab can be integrated with the following enhancements:
+
+- Add GitLab actions to [Gmail actions buttons](gmail_action_buttons_for_gitlab.md).
+- Configure [PlantUML](../administration/integration/plantuml.md)
+or [Kroki](../administration/integration/kroki.md) to use diagrams in AsciiDoc and Markdown documents.
+- Attach merge requests to [Trello](trello_power_up.md) cards.
+- Enable integrated code intelligence powered by [Sourcegraph](sourcegraph.md).
+- Add [Elasticsearch](elasticsearch.md) for [Advanced Search](../user/search/advanced_search.md).
+
+## Integrations
+
+Integration with services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [Integrations](../user/project/integrations/overview.md).
+
+## Troubleshooting
+
+### SSL certificate errors
+
+When trying to integrate GitLab with services using self-signed certificates,
+SSL certificate errors can occur in different parts of the application. Sidekiq
+is a common culprit.
+
+There are two approaches you can take to solve this:
+
+1. Add the root certificate to the trusted chain of the OS.
+1. If using Omnibus, you can add the certificate to the GitLab trusted certificates.
+
+**OS main trusted chain**
+
+This [resource](https://manuals.gfi.com/en/kerio/connect/content/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html)
+has all the information you need to add a certificate to the main trusted chain.
+
+This [answer](https://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu)
+at Super User also has relevant information.
+
+**Omnibus Trusted Chain**
+
+[Install the self signed certificate or custom certificate authorities](https://docs.gitlab.com/omnibus/common_installation_problems/README.html#using-self-signed-certificate-or-custom-certificate-authorities)
+in to Omnibus GitLab.
+
+It is enough to concatenate the certificate to the main trusted certificate
+however it may be overwritten during upgrades:
+
+```shell
+cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem
+```
+
+After that restart GitLab with:
+
+```shell
+sudo gitlab-ctl restart
+```
diff --git a/doc/integration/jira/img/jira_merge_request_close.png b/doc/integration/jira/img/jira_merge_request_close.png
deleted file mode 100644
index 9a176daf5f4..00000000000
--- a/doc/integration/jira/img/jira_merge_request_close.png
+++ /dev/null
diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md
index d2cab59742b..1f2ab3d79dc 100644
--- a/doc/integration/jira/issues.md
+++ b/doc/integration/jira/issues.md
@@ -6,168 +6,157 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Jira integration issue management **(FREE)**
 
-By now you should have [configured Jira](development_panel.md#configuration) and enabled the
-[Jira service in GitLab](development_panel.md#configure-gitlab). If everything is set up correctly
-you should be able to reference and close Jira issues by just mentioning their
-ID in GitLab commits and merge requests.
+Integrating issue management with Jira requires you to [configure Jira](development_panel.md#configuration)
+and [enable the Jira service](development_panel.md#configure-gitlab) in GitLab.
+After you configure and enable the integration, you can reference and close Jira
+issues by mentioning the Jira ID in GitLab commits and merge requests.
 
-Jira issue IDs must be formatted in uppercase for the integration to work.
+The Jira integration requires to you format any Jira issue IDs in uppercase.
 
 ## Reference Jira issues
 
-When GitLab project has Jira issue tracker configured and enabled, mentioning
-Jira issues in GitLab automatically adds a comment in Jira issue with the
-link back to GitLab. This means that in comments in merge requests and commits
-referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the
-format:
+With this integration, you can cross-reference Jira issues while you work in
+GitLab issues and merge requests. Mention a Jira issue in a GitLab issue,
+merge request, or comment, and GitLab adds a formatted comment to the Jira issue.
+The comment links back to your work in GitLab.
 
-```plaintext
-USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]:
-ENTITY_TITLE
+For example, this commit references the Jira issue `GIT-1`:
+
+```shell
+git commit -m "GIT-1 this is a test commit"
 ```
 
-- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab.
-- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned.
-- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request.
-- `PROJECT_NAME` GitLab project name.
-- `ENTITY_TITLE` Merge request title or commit message first line.
+GitLab adds a reference to the **Issue Links** section of Jira issue `GIT-1`:
 
-![example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
+![Example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
 
-For example, the following commit references the Jira issue with `PROJECT-1` as its ID:
+GitLab also adds a comment to the issue, and uses this format:
 
-```shell
-git commit -m "PROJECT-1 Fix spelling and grammar"
+```plaintext
+USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]:
+ENTITY_TITLE
 ```
 
-## Close Jira issues
+- `USER`: The name of the user who mentioned the issue, linked to their GitLab user profile.
+- `COMMENTLINK`: A link to where the Jira issue was mentioned.
+- `RESOURCE_NAME`: The type of resource, such as a commit or merge request, which referenced the issue.
+- `PROJECT_NAME`: The GitLab project name.
+- `ENTITY_TITLE`: The title of the merge request, or the first line of the commit.
 
-Jira issues can be closed directly from GitLab by using trigger words in
-commits and merge requests. When a commit which contains the trigger word
-followed by the Jira issue ID in the commit message is pushed, GitLab
-adds a comment in the mentioned Jira issue and immediately closes it (provided
-the transition ID was set up correctly).
+You can [disable comments](#disable-comments-on-jira-issues) on issues.
 
-There are currently three trigger words, and you can use either one to achieve
-the same goal:
+## Close Jira issues in GitLab
 
-- `Resolves PROJECT-1`
-- `Closes PROJECT-1`
-- `Fixes PROJECT-1`
-
-where `PROJECT-1` is the ID of the Jira issue.
+If you have configured GitLab transition IDs, you can close a Jira issue directly
+from GitLab. Use a trigger word followed by a Jira issue ID in a commit or merge request.
+When you push a commit containing a trigger word and Jira issue ID, GitLab:
 
-Note the following:
+1. Comments in the mentioned Jira issue.
+1. Closes the Jira issue. If the Jira issue has a resolution, it isn't transitioned.
 
-- Only commits and merges into the project's default branch (usually `master`)
-  close an issue in Jira. You can change your project's default branch under
-  [project settings](img/jira_project_settings.png).
-- The Jira issue is not transitioned if it has a resolution.
+For example, use any of these trigger words to close the Jira issue `PROJECT-1`:
 
-Let's consider the following example:
-
-1. For the project named `PROJECT` in Jira, we implemented a new feature
-   and created a merge request in GitLab.
-1. This feature was requested in Jira issue `PROJECT-7` and the merge request
-   in GitLab contains the improvement
-1. In the merge request description we use the issue closing trigger
-   `Closes PROJECT-7`.
-1. Once the merge request is merged, the Jira issue is automatically closed
-   with a comment and an associated link to the commit that resolved the issue.
+- `Resolves PROJECT-1`
+- `Closes PROJECT-1`
+- `Fixes PROJECT-1`
 
-In the following screenshot you can see what the link references to the Jira
-issue look like.
+The commit or merge request must target your project's [default branch](../../user/project/repository/branches/default.md).
+You can change your project's default branch under [project settings](img/jira_project_settings.png).
 
-![A Git commit that causes the Jira issue to be closed](img/jira_merge_request_close.png)
+### Use case for closing issues
 
-Once this merge request is merged, the Jira issue is automatically closed
-with a link to the commit that resolved the issue.
+Consider this example:
 
-![The GitLab integration closes Jira issue](img/jira_service_close_issue.png)
+1. A user creates Jira issue `PROJECT-7` to request a new feature.
+1. You create a merge request in GitLab to build the requested feature.
+1. In the merge request, you add the issue closing trigger `Closes PROJECT-7`.
+1. When the merge request is merged:
+   - GitLab closes the Jira issue for you:
+     ![The GitLab integration closes Jira issue](img/jira_service_close_issue.png)
+   - GitLab adds a formatted comment to Jira, linking back to the commit that
+     resolved the issue. You can [disable comments](#disable-comments-on-jira-issues).
 
 ## View Jira issues **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
 
 You can browse, search, and view issues from a selected Jira project directly in GitLab,
-if your GitLab administrator [has configured it](development_panel.md#configure-gitlab):
-
-1. In the left navigation bar, go to **Jira > Issues list**.
-1. The issue list sorts by **Created date** by default, with the newest issues listed at the top:
-
-   ![Jira issues integration enabled](img/open_jira_issues_list_v13.2.png)
+if your GitLab administrator [has configured it](development_panel.md#configure-gitlab).
 
-1. To display the most recently updated issues first, click **Last updated**.
-1. In GitLab versions 13.10 and later, you can view [individual Jira issues](#view-a-jira-issue).
+To do this, in GitLab, go to your project and select **Jira > Issues list**. The issue list
+sorts by **Created date** by default, with the newest issues listed at the top:
 
-Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html):
+![Jira issues integration enabled](img/open_jira_issues_list_v13.2.png)
 
-- The **Open** tab displays all issues with a Jira status in any category other than Done.
-- The **Closed** tab displays all issues with a Jira status categorized as Done.
-- The **All** tab displays all issues of any status.
+- To display the most recently updated issues first, select **Last updated**.
+- You can [search and filter](#search-and-filter-the-issues-list) the issues list.
+- In GitLab [versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/299832),
+  you can select an issue from the list to view it in GitLab:
+  ![Jira issue detail view](img/jira_issue_detail_view_v13.10.png)
 
-## View a Jira issue
+Issues are grouped into tabs based on their
+[Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html):
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10 behind a feature flag, disabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11.
-
-When viewing the [Jira issues list](#view-jira-issues), select an issue from the
-list to open it in GitLab:
-
-![Jira issue detail view](img/jira_issue_detail_view_v13.10.png)
+- **Open** tab: All issues with a Jira status in any category other than Done.
+- **Closed** tab: All issues with a Jira status categorized as Done.
+- **All** tab: All issues of any status.
 
 ## Search and filter the issues list
 
 To refine the list of issues, use the search bar to search for any text
-contained in an issue summary (title) or description.
-
-You can also filter by labels, status, reporter, and assignee using URL parameters.
-Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622).
+contained in an issue summary (title) or description. Use any combination
+of these filters:
 
 - To filter issues by `labels`, specify one or more labels as part of the `labels[]`
-parameter in the URL. When using multiple labels, only issues that contain all specified
-labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA`
-
-- To filter issues by `status`, specify the `status` parameter in the URL.
-`/-/integrations/jira/issues?status=In Progress`
-
+  parameter in the URL. When using multiple labels, only issues that contain all specified
+  labels are listed: `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA`
+- To filter issues by `status`, specify the `status` parameter in the URL:
+  `/-/integrations/jira/issues?status=In Progress`
 - To filter issues by `reporter`, specify a reporter's Jira display name for the
-`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith`
-
+  `author_username` parameter in the URL: `/-/integrations/jira/issues?author_username=John Smith`
 - To filter issues by `assignee`, specify their Jira display name for the
-`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith`
+  `assignee_username` parameter in the URL: `/-/integrations/jira/issues?assignee_username=John Smith`
+
+Enhancements to use these filters through the user interface
+[are planned](https://gitlab.com/groups/gitlab-org/-/epics/3622).
 
 ## Automatic issue transitions
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10.
 
-In this mode the referenced Jira issue is transitioned to the next available status with a category of "Done".
+When you configure automatic issue transitions, you can transition a referenced
+Jira issue to the next available status with a category of **Done**. To configure
+this setting:
 
-See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option.
+1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
+1. Select the **Enable Jira transitions** check box.
+1. Select the **Move to Done** option.
 
 ## Custom issue transitions
 
-For advanced workflows you can specify custom Jira transition IDs.
-
-See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting, select the **Custom transitions** option, and enter your transition IDs in the text field.
-
-If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. If a transition fails the sequence is aborted.
-
-To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view.
-The transition IDs display in the **Transitions** column.
-
-On Jira Server you can get the transition IDs in either of the following ways:
-
-1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions`
-   using an issue that is in the appropriate "open" state
-1. By mousing over the link for the transition you want and looking for the
-   "action" parameter in the URL
-
-Note that the transition ID may vary between workflows (for example, bug vs. story),
-even if the status you are changing to is the same.
-
-## Disabling comments on Jira issues
-
-You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue.
-
-See the [Configure GitLab](development_panel.md#configure-gitlab) section and uncheck the **Enable comments** setting.
+For advanced workflows, you can specify custom Jira transition IDs:
+
+1. Use the method based on your Jira subscription status:
+   - *(For users of Jira Cloud)* Obtain your transition IDs by editing a workflow
+     in the **Text** view. The transition IDs display in the **Transitions** column.
+   - *(For users of Jira Server)* Obtain your transition IDs in one of these ways:
+     - By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions`,
+       using an issue that is in the appropriate "open" state.
+     - By mousing over the link for the transition you want and looking for the
+       **action** parameter in the URL.
+   The transition ID may vary between workflows (for example, a bug instead of a
+   story), even if the status you're changing to is the same.
+1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
+1. Select the **Enable Jira transitions** setting.
+1. Select the **Custom transitions** option.
+1. Enter your transition IDs in the text field. If you insert multiple transition IDs
+   (separated by `,` or `;`), the issue is moved to each state, one after another, in the
+   order you specify. If a transition fails, the sequence is aborted.
+
+## Disable comments on Jira issues
+
+GitLab can cross-link source commits or merge requests with Jira issues without
+adding a comment to the Jira issue:
+
+1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions.
+1. Clear the **Enable comments** check box.
diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md
index ce12e8a6a9b..b552a3f9a1f 100644
--- a/doc/user/application_security/index.md
+++ b/doc/user/application_security/index.md
@@ -156,7 +156,7 @@ rating.
 
 ### Enabling Security Approvals within a project
 
-To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/approvals/rules.md#adding--editing-a-default-approval-rule)
+To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/approvals/rules.md#add-an-approval-rule)
 must be created. A [security scanner job](#security-scanning-tools) must be enabled for
 `Vulnerability-Check`, and a [license scanning](../compliance/license_compliance/index.md#configuration)
 job must be enabled for `License-Check`. When the proper jobs aren't configured, the following
diff --git a/doc/user/index.md b/doc/user/index.md
index 9546b48ec0f..ab159cecdef 100644
--- a/doc/user/index.md
+++ b/doc/user/index.md
@@ -178,7 +178,7 @@ pages and accomplish tasks faster.
 
 ## Integrations
 
-[Integrate GitLab](../integration/README.md) with your preferred tool,
+[Integrate GitLab](../integration/index.md) with your preferred tool,
 such as Trello, Jira, etc.
 
 ## Webhooks
diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md
index 1b157f9a93f..aa668e85156 100644
--- a/doc/user/project/merge_requests/approvals/index.md
+++ b/doc/user/project/merge_requests/approvals/index.md
@@ -67,7 +67,7 @@ in your project's settings.
 
 If you enable [approval rule overrides](settings.md#prevent-overriding-default-approvals),
 merge requests created before a change to default approval rules are not affected.
-The only exceptions are changes to the [target branch](rules.md#scoped-to-protected-branch)
+The only exceptions are changes to the [target branch](rules.md#approvals-for-protected-branches)
 of the rule.
 
 ## Optional approvals
@@ -117,6 +117,11 @@ You can modify your external approval rules
 
 The lack of an external approval doesn't block the merging of a merge request.
 
+When [approval rule overrides](settings.md#prevent-overriding-default-approvals) are allowed,
+changes to default approval rules will **not** be applied to existing
+merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches)
+of the rule.
+
 To learn more about use cases, feature discovery, and development timelines,
 see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869).
 
diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md
index 0105ff23fff..3e40936f887 100644
--- a/doc/user/project/merge_requests/approvals/rules.md
+++ b/doc/user/project/merge_requests/approvals/rules.md
@@ -7,201 +7,226 @@ type: reference, concepts
 
 # Merge request approval rules
 
-Approval rules define how many approvals a merge request must receive before it can
-be merged, and optionally which users should do the approving. Approvals can be defined:
+Approval rules define how many [approvals](index.md) a merge request must receive before it can
+be merged, and which users should do the approving. You can define approval rules:
 
-- [As project defaults](#adding--editing-a-default-approval-rule).
-- [Per merge request](#editing--overriding-approval-rules-per-merge-request).
+- [As project defaults](#add-an-approval-rule).
+- [Per merge request](#edit-or-override-merge-request-approval-rules).
+- [At the instance level](../../../admin_area/merge_requests_approvals.md)
 
-If no approval rules are defined, any user can approve a merge request. However, the default
-minimum number of required approvers can still be set in the
-[settings for merge request approvals](settings.md).
+If you don't define a [default approval rule](#add-an-approval-rule),
+any user can approve a merge request. Even if you don't define a rule, you can still
+enforce a [minimum number of required approvers](settings.md) in the project's settings.
 
-You can opt to define one single rule to approve a merge request among the available rules
-or choose more than one with [multiple approval rules](#multiple-approval-rules).
+You can define a single rule to approve merge requests from among the available
+rules, or you can select [multiple approval rules](#add-multiple-approval-rules).
 
-NOTE:
-On GitLab.com, you can add a group as an approver if you're a member of that group or the
-group is public.
+Merge requests that target a different project, such as from a fork to the upstream project,
+use the default approval rules from the target (upstream) project, not the source (fork).
 
-## Eligible Approvers
+## Add an approval rule
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget.
+To add a merge request approval rule:
 
-The following users can approve merge requests:
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**, and then 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`
+   creates a required rule.
+1. To add users or groups as approvers, search for users or groups that are
+   [eligible to approve](#eligible-approvers), and select **Add**. GitLab suggests approvers based on
+   previous authors of the files changed by the merge request.
 
-- Users who have been added as approvers at the project or merge request levels with
-  developer or higher [permissions](../../../permissions.md).
-- [Code owners](#code-owners-as-eligible-approvers) of the files changed by the merge request
-  that have developer or higher [permissions](../../../permissions.md).
+     NOTE:
+     On GitLab.com, you can add a group as an approver if you're a member of that group or the
+     group is public.
 
-An individual user can be added as an approver for a project if they are a member of:
+1. Select **Add approval rule**.
 
-- The project.
-- The project's immediate parent group.
-- A group that has access to the project via a [share](../../members/share_project_with_groups.md).
+Users of GitLab Premium and higher tiers can create [additional approval rules](#add-multiple-approval-rules).
 
-A group of users can also be added as approvers, though they only count as approvers if
-they have direct membership to the group. 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).
+Your configuration for approval rule overrides determines if the new rule is applied
+to existing merge requests:
 
-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, and users who have committed
-to the merge request, do not count as eligible approvers,
-if [**Prevent author approval**](settings.md#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default)
-and [**Prevent committers approval**](settings.md#prevent-approval-of-merge-requests-by-their-committers) (disabled by default)
-are enabled on the project settings.
+- If [approval rule overrides](settings.md#prevent-overriding-default-approvals) are allowed,
+  changes to these default rules are not applied to existing merge requests, except for
+  changes to the [target branch](#approvals-for-protected-branches) of the rule.
+- If approval rule overrides are not allowed, all changes to default rules
+  are applied to existing merge requests. Any approval rules that were previously
+  manually [overridden](#edit-or-override-merge-request-approval-rules) during the
+  period when approval rule overrides where allowed, are not modified.
 
-When an eligible approver comments on a merge request, it displays in the
-**Commented by** column of the Approvals widget. It indicates who participated in
-the merge request review. Authors and reviewers can also identify who they should reach out
-to if they have any questions about the content of the merge request.
+## Edit an approval rule
 
-### Implicit Approvers
+To edit a merge request approval rule:
 
-If the number of required approvals is greater than the number of assigned approvers,
-approvals from other users counts 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.
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**, and then select **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:
+   - *To add users or groups as approvers,* search for users or groups that are
+     [eligible to approve](#eligible-approvers), and select **Add**.
 
-### Code Owners as eligible approvers
+     NOTE:
+     On GitLab.com, you can add a group as an approver if you're a member of that group or the
+     group is public.
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5.
-> - Moved to GitLab Premium in 13.9.
+   - *To remove users or groups,* identify the group or user to remove, and
+     select **{remove}** **Remove**.
+1. Select **Update approval rule**.
 
-If you add [Code Owners](../../code_owners.md) to your repository, the owners to the
-corresponding files become eligible approvers, together with members with Developer
-or higher [permissions](../../../permissions.md).
+## Add multiple approval rules **(PREMIUM)**
 
-To enable this merge request approval rule:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab Premium 11.10.
 
-1. Navigate to your project's **Settings > General** and expand
-   **Merge request (MR) approvals**.
-1. Locate **Any eligible user** and choose the number of approvals required.
+In GitLab Premium and higher tiers, you can enforce multiple approval rules on a
+merge request, and multiple default approval rules for a project. If your tier
+supports multiple default rules:
 
-![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v12_7.png)
+- When [adding](#add-an-approval-rule) or [editing](#edit-an-approval-rule) an approval rule
+  for a project, GitLab displays the **Add approval rule** button even after a rule is defined.
+- When editing or overriding multiple approval rules
+  [on a merge request](#edit-or-override-merge-request-approval-rules), GitLab
+  displays the **Add approval rule** button even after a rule is defined.
 
-Once set, merge requests can only be merged once approved by the
-number of approvals you've set. GitLab accepts approvals from
-users with Developer or higher permissions, as well as by Code Owners,
-indistinguishably.
+When an [eligible approver](#eligible-approvers) approves a merge request, it
+reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to:
 
-Alternatively, you can **require**
-[Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)**
+![Approvals premium merge request widget](img/approvals_premium_mr_widget_v13_3.png)
 
-## Merge Request approval segregation of duties
+## Eligible approvers
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4.
-> - Moved to Premium in 13.9.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget.
 
-Managers or operators with [Reporter permissions](../../../permissions.md#project-members-permissions)
-to a project sometimes need to be required approvers of a merge request,
-before a merge to a protected branch begins. These approvers aren't allowed
-to push or merge code to any branches.
+To be eligible as an approver for a project, a user must be a member of one or
+more of these:
 
-To enable this access:
+- The project.
+- The project's immediate parent [group](#group-approvers).
+- A group that has access to the project via a [share](../../members/share_project_with_groups.md).
+- A [group added as approvers](#group-approvers).
 
-1. [Create a new group](../../../group/index.md#create-a-group), and then
-   [add the user to the group](../../../group/index.md#add-users-to-a-group),
-   ensuring you select the Reporter role for the user.
-1. [Share the project with your group](../../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users),
-   based on the Reporter role.
-1. Navigate to your project's **Settings > General**, and in the
-   **Merge request (MR) approvals** section, click **Expand**.
-1. Select **Add approval rule** or **Update approval rule**.
-1. [Add the group](../../../group/index.md#create-a-group) to the permission list.
+The following users can approve merge requests if they have Developer or
+higher [permissions](../../../permissions.md):
 
-![Update approval rule](img/update_approval_rule_v13_10.png)
+- Users added as approvers at the project or merge request level.
+- Users who are [Code owners](#code-owners-as-eligible-approvers) of the files
+  changed in the merge request.
 
-## Adding / editing a default approval rule
+To show who has participated in the merge request review, the Approvals widget in
+a merge request displays a **Commented by** column. This column lists eligible approvers
+who commented on the merge request. It helps authors and reviewers identify who to
+contact with questions about the merge request's content.
 
-To add or edit the default merge request approval rule:
+If the number of required approvals is greater than the number of assigned approvers,
+approvals from other users with Developer [permissions](../../../permissions.md) or higher
+in the project counts toward meeting the required number of approvals, even if the
+users were not explicitly listed in the approval rules.
 
-1. Navigate to your project's **Settings > General** and expand **Merge request (MR) approvals**.
+### Group approvers
 
-1. Click **Add approval rule**, or **Edit**.
-   - Add or change the **Rule name**.
-   - Set the number of required approvals in **Approvals required**. The minimum value is `0`.
-   - (Optional) Search for users or groups that are [eligible to approve](#eligible-approvers)
-     merge requests and click the **Add** button to add them as approvers. Before typing
-     in the search field, approvers are suggested based on the previous authors of
-     the files being changed by the merge request.
-   - (Optional) Click the **{remove}** **Remove** button next to a group or user to delete it from
-     the rule.
-1. Click **Add approval rule** or **Update approval rule**.
+You can add a group of users as approvers, but those users count as approvers only if
+they have direct membership to the group. 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).
 
-When [approval rule overrides](settings.md#prevent-overriding-default-approvals) are allowed,
-changes to these default rules are not applied to existing merge
-requests, except for changes to the [target branch](#scoped-to-protected-branch) of
-the rule.
+A user's membership in an approvers group affects their individual ability to
+approve in these ways:
 
-When approval rule overrides are not allowed, all changes to these default rules
-are applied to existing merge requests. Any approval rules that had previously been
-manually [overridden](#editing--overriding-approval-rules-per-merge-request) during a
-period when approval rule overrides where allowed, are not modified.
+- A user already part of a group approver who is later added as an individual approver
+  counts as one approver, and not two.
+- Merge request authors do not count as eligible approvers on their own merge requests by default.
+  To change this behavior, disable the
+  [**Prevent author approval**](settings.md#allowing-merge-request-authors-to-approve-their-own-merge-requests)
+  project setting.
+- Committers to merge requests can approve a merge request. To change this behavior, enable the
+  [**Prevent committers approval**](settings.md#prevent-approval-of-merge-requests-by-their-committers)
+  project setting.
 
-NOTE:
-If a merge request targets a different project, such as from a fork to the upstream project,
-the default approval rules are taken from the target (upstream) project, not the
-source (fork).
+### Code owners as eligible approvers
 
-### Editing / overriding approval rules per merge request
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5.
+> - Moved to GitLab Premium in 13.9.
 
-> Introduced in GitLab Enterprise Edition 9.4.
+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:
 
-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](settings.md#prevent-overriding-default-approvals).
+1. Go to your project and select **Settings > General**.
+1. Expand **Merge request (MR) approvals**.
+1. Locate **Any eligible user** and select the number of approvals required:
 
-One possible scenario would be to add more approvers than were defined in the default
-settings.
+   ![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v12_7.png)
 
-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).
+You can also
+[require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners)
+for protected branches. **(PREMIUM)**
 
-## Set up an optional approval rule
+## Merge request approval segregation of duties
 
-MR approvals can be configured to be optional, which can help if you're working
-on a team where approvals are appreciated, but not required.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4.
+> - Moved to GitLab Premium in 13.9.
 
-To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`.
+You may need to grant users with [Reporter permissions](../../../permissions.md#project-members-permissions),
+permission to approve merge requests before they can merge to a protected branch.
+Some users (like managers) may not need permission to push or merge code, but still need
+oversight on proposed work. To enable approval permissions for these users without
+granting them push access:
 
-You can also set an optional approval rule through the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule), by setting the `approvals_required` attribute to `0`.
+1. [Create a new group](../../../group/index.md#create-a-group).
+1. [Add the user to the group](../../../group/index.md#add-users-to-a-group),
+   and select the Reporter role for the user.
+1. [Share the project with your group](../../members/share_project_with_groups.md#sharing-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**.
+1. [Add the group](../../../group/index.md#create-a-group) to the permission list.
 
-## Multiple approval rules **(PREMIUM)**
+   ![Update approval rule](img/update_approval_rule_v13_10.png)
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
+### Edit or override merge request approval rules
 
-In GitLab Premium, it is possible to have multiple approval rules per merge request,
-as well as multiple default approval rules per project.
+By default, the merge request author (or a user with sufficient [permissions](../../../permissions.md))
+can edit the approval rule listed in a merge request. When editing an approval rule
+on a merge request, you can either add or remove approvers:
 
-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 is available to add more rules, even after
-a rule is already defined.
+1. In the merge request, find the **Approval rules section**.
+1. When creating a new merge request, scroll to the **Approval Rules** section,
+   and add or remove your desired approval rules before selecting **Create merge request**.
+1. When viewing an existing merge request:
+   1. Select **Edit**.
+   1. Scroll to the **Approval Rules** section.
+   1. Add or remove your desired approval rules.
+   1. Select **Save changes**.
 
-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 is available to add more rules, even after
-a rule is already defined.
+Administrators can change the [merge request approvals settings](settings.md#prevent-overriding-default-approvals)
+to prevent users from overriding approval rules for merge requests.
 
-When an [eligible approver](#eligible-approvers) approves a merge request, it
-reduces the number of approvals left for all rules that the approver belongs to.
+## Configure optional approval rules
 
-![Approvals premium merge request widget](img/approvals_premium_mr_widget_v13_3.png)
+Merge request approvals can be optional for projects where approvals are
+appreciated, but not required. To make an approval rule optional:
 
-## Scoped to protected branch **(PREMIUM)**
+- When you [create or edit a rule](#edit-an-approval-rule), set **Approvals required** to `0`.
+- Use the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule)
+  to set the `approvals_required` attribute to `0`.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8.
+## Approvals for protected branches **(PREMIUM)**
 
-Approval rules are often only relevant to specific branches, like `master`.
-When configuring [**Default Approval Rules**](#adding--editing-a-default-approval-rule)
-these can be scoped to all the protected branches at once by navigating to your project's
-**Settings**, expanding **Merge request (MR) approvals**, and selecting **Any branch** from
-the **Target branch** dropdown.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab Premium 12.8.
 
-Alternatively, you can select a very specific protected branch from the **Target branch** dropdown:
+Approval rules are often relevant only to specific branches, like your
+[default branch](../../repository/branches/default.md). To configure an
+approval rule for certain branches:
 
-![Scoped to protected branch](img/scoped_to_protected_branch_v13_10.png)
+1. [Create an approval rule](#add-an-approval-rule).
+1. Go to your project and select **Settings**.
+1. Expand **Merge request (MR) approvals**.
+1. Select a **Target branch**:
+   - To protect all branches, select **Any branch**.
+   - To select a specific branch, select it from the list:
 
-To enable this configuration, see [Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners).
+     ![Scoped to protected branch](img/scoped_to_protected_branch_v13_10.png)
+1. To enable this configuration, read
+   [Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners).
diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md
index 8f44e6d1991..0ca1d462fef 100644
--- a/doc/user/project/merge_requests/approvals/settings.md
+++ b/doc/user/project/merge_requests/approvals/settings.md
@@ -13,7 +13,7 @@ The settings for Merge Request Approvals are found by going to
 ## Prevent overriding default approvals
 
 Regardless of the approval rules you choose for your project, users can edit them in every merge
-request, overriding the [rules you set as default](rules.md#adding--editing-a-default-approval-rule).
+request, overriding the [rules you set as default](rules.md#add-an-approval-rule).
 To prevent that from happening:
 
 1. Select the **Prevent users from modifying MR approval rules in merge requests.** checkbox.