Add latest changes from gitlab-org/gitlab@master

12 files changed, 431 insertions, 314 deletions

diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md
index 74672831a64..a8b0bdeb7da 100644
--- a/doc/administration/geo/replication/geo_validation_tests.md
+++ b/doc/administration/geo/replication/geo_validation_tests.md
@@ -11,37 +11,36 @@ The following are GitLab upgrade validation tests we performed.
 
 ### February 2020
 
-[Upgrade Geo HA installation](https://gitlab.com/gitlab-org/gitlab/-/issues/201837):
+[Upgrade Geo multi-server installation](https://gitlab.com/gitlab-org/gitlab/-/issues/201837):
 
-- Description: Tested upgrading from GitLab 12.7.5 to the latest GitLab 12.8 package in a high
-  availability configuration.
+- Description: Tested upgrading from GitLab 12.7.5 to the latest GitLab 12.8 package in a multi-server
+  configuration.
 - Outcome: Partial success because we did not run the looping pipeline during the demo to monitor
   downtime.
 
 ### January 2020
 
-[Upgrade Geo HA installation](https://gitlab.com/gitlab-org/gitlab/-/issues/200085):
+[Upgrade Geo multi-server installation](https://gitlab.com/gitlab-org/gitlab/-/issues/200085):
 
-- Description: Tested upgrading from GitLab 12.6.x to the latest GitLab 12.7 package in a high
-  availability configuration.
+- Description: Tested upgrading from GitLab 12.6.x to the latest GitLab 12.7 package in a multi-server
+  configuration.
 - Outcome: Upgrade test was successful.
 - Follow up issues:
   - [Investigate Geo end-to-end test failures](https://gitlab.com/gitlab-org/gitlab/issues/201823).
   - [Add more logging to Geo end-to-end tests](https://gitlab.com/gitlab-org/gitlab/issues/201830).
   - [Excess service restarts during zero-downtime upgrade](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5047).
 
-[Upgrade Geo HA installation](https://gitlab.com/gitlab-org/gitlab/-/issues/199836):
+[Upgrade Geo multi-server installation](https://gitlab.com/gitlab-org/gitlab/-/issues/199836):
 
-- Description: Tested upgrading from GitLab 12.5.7 to GitLab 12.6.6 in a high availability
-  configuration.
+- Description: Tested upgrading from GitLab 12.5.7 to GitLab 12.6.6 in a multi-server configuration.
 - Outcome: Upgrade test was successful.
 - Follow up issue:
   [Update documentation for zero-downtime upgrades to ensure deploy node it not in use](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5046).
 
-[Upgrade Geo HA installation](https://gitlab.com/gitlab-org/gitlab/-/issues/37044):
+[Upgrade Geo multi-server installation](https://gitlab.com/gitlab-org/gitlab/-/issues/37044):
 
-- Description: Tested upgrading from GitLab 12.4.x to the latest GitLab 12.5 package in a high
-  availability configuration.
+- Description: Tested upgrading from GitLab 12.4.x to the latest GitLab 12.5 package in a multi-server
+  configuration.
 - Outcome: Upgrade test was successful.
 - Follow up issues:
   - [Investigate why HTTP push spec failed on primary node](https://gitlab.com/gitlab-org/gitlab/issues/199825).
@@ -49,17 +48,17 @@ The following are GitLab upgrade validation tests we performed.
 
 ### October 2019
 
-[Upgrade Geo HA installation](https://gitlab.com/gitlab-org/gitlab/-/issues/35262):
+[Upgrade Geo multi-server installation](https://gitlab.com/gitlab-org/gitlab/-/issues/35262):
 
-- Description: Tested upgrading from GitLab 12.3.5 to GitLab 12.4.1 in a high availability configuration.
+- Description: Tested upgrading from GitLab 12.3.5 to GitLab 12.4.1 in a multi-server configuration.
 - Outcome: Upgrade test was successful.
 
-[Upgrade Geo HA installation](https://gitlab.com/gitlab-org/gitlab/-/issues/32437):
+[Upgrade Geo multi-server installation](https://gitlab.com/gitlab-org/gitlab/-/issues/32437):
 
 - Description: Tested upgrading from GitLab 12.2.8 to GitLab 12.3.5.
 - Outcome: Upgrade test was successful.
 
-[Upgrade Geo HA installation](https://gitlab.com/gitlab-org/gitlab/-/issues/32435):
+[Upgrade Geo multi-server installation](https://gitlab.com/gitlab-org/gitlab/-/issues/32435):
 
 - Description: Tested upgrading from GitLab 12.1.9 to GitLab 12.2.8.
 - Outcome: Partial success due to possible misconfiguration issues.
@@ -74,7 +73,7 @@ The following are PostgreSQL upgrade validation tests we performed.
 
 - Description: Prior to making PostgreSQL 11 the default version of PostgreSQL in GitLab 12.10, we
   tested upgrading to PostgreSQL 11 in Geo deployments on GitLab 12.9.
-- Outcome: Partially successful. Issues were discovered in HA configurations with a separate
+- Outcome: Partially successful. Issues were discovered in multi-server configurations with a separate
   tracking database and concerns were raised about allowing automatic upgrades when Geo enabled.
 - Follow up issues:
   - [`replicate-geo-database` incorrectly tries to back up repositories](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5241).
@@ -96,6 +95,6 @@ The following are PostgreSQL upgrade validation tests we performed.
   various upgrade scenarios from GitLab 11.11.5 through to GitLab 12.1.8.
 - Outcome: Multiple issues were found when upgrading and addressed in follow-up issues.
 - Follow up issues:
-  - [`gitlab-ctl` reconfigure fails on Redis node in HA Geo setup](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4706).
-  - [HA with Geo upgrade from 12.0.9 to 12.1.9 does not upgrade PostgreSQL](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4705).
-  - [Refresh foreign tables fails on app server in HA setup after upgrade to 12.1.9](https://gitlab.com/gitlab-org/gitlab/-/issues/32119).
+  - [`gitlab-ctl` reconfigure fails on Redis node in multi-server Geo setup](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4706).
+  - [Geo multi-server upgrade from 12.0.9 to 12.1.9 does not upgrade PostgreSQL](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4705).
+  - [Refresh foreign tables fails on app server in multi-server setup after upgrade to 12.1.9](https://gitlab.com/gitlab-org/gitlab/-/issues/32119).
diff --git a/doc/administration/geo/replication/high_availability.md b/doc/administration/geo/replication/high_availability.md
index 3cc6502e720..9322c4cc417 100644
--- a/doc/administration/geo/replication/high_availability.md
+++ b/doc/administration/geo/replication/high_availability.md
@@ -1,12 +1,12 @@
-# Geo High Availability **(PREMIUM ONLY)**
+# Geo for multiple servers **(PREMIUM ONLY)**
 
 This document describes a minimal reference architecture for running Geo
-in a high availability configuration. If your HA setup differs from the one
+in a multi-server configuration. If your multi-server setup differs from the one
 described, it is possible to adapt these instructions to your needs.
 
 ## Architecture overview
 
-![Geo HA Diagram](../../high_availability/img/geo-ha-diagram.png)
+![Geo multi-server diagram](../../high_availability/img/geo-ha-diagram.png)
 
 _[diagram source - GitLab employees only](https://docs.google.com/drawings/d/1z0VlizKiLNXVVVaERFwgsIOuEgjcUqDTWPdQYsE7Z4c/edit)_
 
@@ -23,36 +23,36 @@ The only external way to access the two Geo deployments is by HTTPS at
 NOTE: **Note:**
 The **primary** and **secondary** Geo deployments must be able to communicate to each other over HTTPS.
 
-## Redis and PostgreSQL High Availability
+## Redis and PostgreSQL for multiple servers
 
 Geo supports:
 
-- Redis and PostgreSQL on the **primary** node configured for high availability
-- Redis on **secondary** nodes configured for high availability.
+- Redis and PostgreSQL on the **primary** node configured for multiple servers.
+- Redis on **secondary** nodes configured for multiple servers.
 
 NOTE: **Note:**
-Support for PostgreSQL on **secondary** nodes in high availability configuration
+Support for PostgreSQL on **secondary** nodes in multi-server configuration
 [is planned](https://gitlab.com/groups/gitlab-org/-/epics/2536).
 
 Because of the additional complexity involved in setting up this configuration
-for PostgreSQL and Redis, it is not covered by this Geo HA documentation.
+for PostgreSQL and Redis, it is not covered by this Geo multi-server documentation.
 
-For more information about setting up a highly available PostgreSQL cluster and Redis cluster using the omnibus package see the high availability documentation for
+For more information about setting up a multi-server PostgreSQL cluster and Redis cluster using the omnibus package see the multi-server documentation for
 [PostgreSQL](../../high_availability/database.md) and
 [Redis](../../high_availability/redis.md), respectively.
 
 NOTE: **Note:**
 It is possible to use cloud hosted services for PostgreSQL and Redis, but this is beyond the scope of this document.
 
-## Prerequisites: Two working GitLab HA clusters
+## Prerequisites: Two working GitLab multi-server clusters
 
 One cluster will serve as the **primary** node. Use the
-[GitLab HA documentation](../../reference_architectures/index.md) to set this up. If
+[GitLab multi-server documentation](../../reference_architectures/index.md) to set this up. If
 you already have a working GitLab instance that is in-use, it can be used as a
 **primary**.
 
 The second cluster will serve as the **secondary** node. Again, use the
-[GitLab HA documentation](../../reference_architectures/index.md) to set this up.
+[GitLab multi-server documentation](../../reference_architectures/index.md) to set this up.
 It's a good idea to log in and test it, however, note that its data will be
 wiped out as part of the process of replicating from the **primary**.
 
@@ -85,8 +85,8 @@ After making these changes, [reconfigure GitLab](../../restart_gitlab.md#omnibus
 
 NOTE: **Note:** PostgreSQL and Redis should have already been disabled on the
 application servers, and connections from the application servers to those
-services on the backend servers configured, during normal GitLab HA set up. See
-high availability configuration documentation for
+services on the backend servers configured, during normal GitLab multi-server set up. See
+multi-server configuration documentation for
 [PostgreSQL](../../high_availability/database.md#configuring-the-application-nodes)
 and [Redis](../../high_availability/redis.md#example-configuration-for-the-gitlab-application).
 
@@ -103,7 +103,7 @@ and [Redis](../../high_availability/redis.md#example-configuration-for-the-gitla
 
 ## Configure a **secondary** node
 
-A **secondary** cluster is similar to any other GitLab HA cluster, with two
+A **secondary** cluster is similar to any other GitLab multi-server cluster, with two
 major differences:
 
 - The main PostgreSQL database is a read-only replica of the **primary** node's
@@ -112,8 +112,8 @@ major differences:
   called the "tracking database", which tracks the synchronization state of
   various resources.
 
-Therefore, we will set up the HA components one-by-one, and include deviations
-from the normal HA setup. However, we highly recommend first configuring a
+Therefore, we will set up the multi-server components one-by-one, and include deviations
+from the normal multi-server setup. However, we highly recommend first configuring a
 brand-new cluster as if it were not part of a Geo setup so that it can be
 tested and verified as a working cluster. And only then should it be modified
 for use as a Geo **secondary**. This helps to separate problems that are related
@@ -121,11 +121,10 @@ and are not related to Geo setup.
 
 ### Step 1: Configure the Redis and Gitaly services on the **secondary** node
 
-Configure the following services, again using the non-Geo high availability
+Configure the following services, again using the non-Geo multi-server
 documentation:
 
-- [Configuring Redis for GitLab HA](../../high_availability/redis.md) for high
-  availability.
+- [Configuring Redis for GitLab](../../high_availability/redis.md) for multiple servers.
 - [Gitaly](../../high_availability/gitaly.md), which will store data that is
   synchronized from the **primary** node.
 
@@ -136,7 +135,7 @@ recommended.
 ### Step 2: Configure the main read-only replica PostgreSQL database on the **secondary** node
 
 NOTE: **Note:** The following documentation assumes the database will be run on
-a single node only. PostgreSQL HA on **secondary** nodes is
+a single node only. Multi-server PostgreSQL on **secondary** nodes is
 [not currently supported](https://gitlab.com/groups/gitlab-org/-/epics/2536).
 
 Configure the [**secondary** database](database.md) as a read-only replica of
@@ -276,7 +275,7 @@ application services. These services are enabled selectively in the
 configuration.
 
 Configure the application servers following
-[Configuring GitLab for HA](../../high_availability/gitlab.md), then make the
+[Configuring GitLab for multiple servers](../../high_availability/gitlab.md), then make the
 following modifications:
 
 1. Edit `/etc/gitlab/gitlab.rb` on each application server in the **secondary**
@@ -364,13 +363,13 @@ application servers.
 In this topology, a load balancer is required at each geographic location to
 route traffic to the application servers.
 
-See [Load Balancer for GitLab HA](../../high_availability/load_balancer.md) for
+See [Load Balancer for GitLab with multiple servers](../../high_availability/load_balancer.md) for
 more information.
 
 ### Step 6: Configure the backend application servers on the **secondary** node
 
 The minimal reference architecture diagram above shows all application services
-running together on the same machines. However, for high availability we
+running together on the same machines. However, for multiple servers we
 [strongly recommend running all services separately](../../reference_architectures/index.md).
 
 For example, a Sidekiq server could be configured similarly to the frontend
diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md
index 63c81071cf3..ab2ed4e6d0f 100644
--- a/doc/administration/geo/replication/index.md
+++ b/doc/administration/geo/replication/index.md
@@ -2,7 +2,7 @@
 
 > - Introduced in GitLab Enterprise Edition 8.9.
 > - Using Geo in combination with
->   [High Availability](../../reference_architectures/index.md)
+>   [multi-server architectures](../../reference_architectures/index.md)
 >   is considered **Generally Available** (GA) in
 >   [GitLab Premium](https://about.gitlab.com/pricing/) 10.4.
 
@@ -206,9 +206,9 @@ For information on configuring Geo, see [Geo configuration](configuration.md).
 
 For information on how to update your Geo nodes to the latest GitLab version, see [Updating the Geo nodes](updating_the_geo_nodes.md).
 
-### Configuring Geo high availability
+### Configuring Geo for multiple servers
 
-For information on configuring Geo for high availability, see [Geo High Availability](high_availability.md).
+For information on configuring Geo for multiple servers, see [Geo for multiple servers](high_availability.md).
 
 ### Configuring Geo with Object Storage
 
diff --git a/doc/administration/git_annex.md b/doc/administration/git_annex.md
index cec78d8728d..0d44ed9312c 100644
--- a/doc/administration/git_annex.md
+++ b/doc/administration/git_annex.md
@@ -9,7 +9,7 @@ removed](https://gitlab.com/gitlab-org/gitlab/issues/1648) in GitLab 9.0 (2017/0
 Read through the [migration guide from git-annex to Git LFS](../topics/git/lfs/migrate_from_git_annex_to_git_lfs.md).
 
 The biggest limitation of Git, compared to some older centralized version
-control systems, has been the maximum size of the repositories.
+control systems has been the maximum size of the repositories.
 
 The general recommendation is to not have Git repositories larger than 1GB to
 preserve performance. Although GitLab has no limit (some repositories in GitLab
@@ -21,7 +21,7 @@ larger organizations.
 Videos, photos, audio, compiled binaries, and many other types of files are too
 large. As a workaround, people keep artwork-in-progress in a Dropbox folder and
 only check in the final result. This results in using outdated files, not
-having a complete history and increases the risk of losing work.
+having a complete history, and increases the risk of losing work.
 
 This problem is solved in GitLab Enterprise Edition by integrating the
 [git-annex](https://git-annex.branchable.com/) application.
@@ -39,7 +39,7 @@ configuration options required to enable it.
 
 ### Requirements
 
-`git-annex` needs to be installed both on the server and the client side.
+`git-annex` needs to be installed both on the server and the client-side.
 
 For Debian-like systems (for example, Debian and Ubuntu) this can be achieved by running:
 
@@ -193,7 +193,7 @@ if you want to.
 
 ## Troubleshooting tips
 
-Differences in version of `git-annex` on the GitLab server and on local machines
+Differences in the version of `git-annex` on the GitLab server and on local machines
 can cause `git-annex` to raise unpredicted warnings and errors.
 
 Consult the [Annex upgrade page](https://git-annex.branchable.com/upgrades/) for more information about
diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md
index 57b8cb1a94b..ae4406742d4 100644
--- a/doc/ci/pipelines/settings.md
+++ b/doc/ci/pipelines/settings.md
@@ -130,6 +130,16 @@ in the jobs table.
 A few examples of known coverage tools for a variety of languages can be found
 in the pipelines settings page.
 
+### Download test coverage history
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209121) in GitLab 12.10.
+
+If you want to see the evolution of your project code coverage over time,
+you can download a CSV file with this data. From your project:
+
+1. Go to **{chart}** **Project Analytics > Repository**.
+1. Click **Download raw data (.csv)**
+
 ### Removing color codes
 
 Some test coverage tools output with ANSI color codes that won't be
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index 9c42328810d..f747fb4e06f 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -52,7 +52,7 @@ docs-only merge requests using the following guide:
 
 [Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community.
 
-To ensure that GitLab docs are current, there are special processes and responsibilities for all [feature changes](feature-change-workflow.md)—i.e. development work that impacts the appearance, usage, or administration of a feature.
+To ensure that GitLab docs are current, there are special processes and responsibilities for all [feature changes](feature-change-workflow.md), that is development work that impacts the appearance, usage, or administration of a feature.
 
 However, anyone can contribute [documentation improvements](improvement-workflow.md) that are not associated with a feature change. For example, adding a new doc on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab.
 
diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md
index bf0ecb9c423..4a00968a497 100644
--- a/doc/install/aws/index.md
+++ b/doc/install/aws/index.md
@@ -533,7 +533,7 @@ gitlab=# \q
 
 #### Set up Gitaly
 
-CAUTION: **Caution:** In this architecture, having a single Gitaly server creates a single point of failure. This limitation will be removed once [Gitaly HA](https://gitlab.com/groups/gitlab-org/-/epics/1489) is released.
+CAUTION: **Caution:** In this architecture, having a single Gitaly server creates a single point of failure. This limitation will be removed once [Gitaly Cluster](https://gitlab.com/groups/gitlab-org/-/epics/1489) is released.
 
 Gitaly is a service that provides high-level RPC access to Git repositories.
 It should be enabled and configured on a separate EC2 instance in one of the
diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md
index cd713db0797..a23867ac87a 100644
--- a/doc/user/application_security/sast/index.md
+++ b/doc/user/application_security/sast/index.md
@@ -452,21 +452,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
 
 ## Secret detection
 
-GitLab is also able to detect secrets and credentials that have been unintentionally pushed to the
-repository, such as an API key that allows write access to third-party deployment
-environments.
-
-This check is performed by a specific analyzer during the `sast` job. It runs regardless of the programming
-language of your app, and you don't need to change anything to your
-CI/CD configuration file to turn it on. Results are available in the SAST report.
-
-GitLab currently includes [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) checks.
-
-NOTE: **Note:**
-The secrets analyzer will ignore "Password in URL" vulnerabilities if the password begins
-with a dollar sign (`$`) as this likely indicates the password being used is an environment
-variable. For example, `https://username:$password@example.com/path/to/repo` won't be
-detected, whereas `https://username:password@example.com/path/to/repo` would be detected.
+Learn more about [Secret Detection](../secret_detection).
 
 ## Security Dashboard
 
diff --git a/doc/user/application_security/secret_detection/img/secret-detection-merge-request-ui.png b/doc/user/application_security/secret_detection/img/secret-detection-merge-request-ui.png
new file mode 100644
index 00000000000..17893610f10
--- /dev/null
+++ b/doc/user/application_security/secret_detection/img/secret-detection-merge-request-ui.png
diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md
new file mode 100644
index 00000000000..74dd3c89984
--- /dev/null
+++ b/doc/user/application_security/secret_detection/index.md
@@ -0,0 +1,67 @@
+---
+type: reference, howto
+---
+
+# Secret Detection **(ULTIMATE)**
+
+> [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9.
+
+## Overview
+
+A recurring problem when developing applications is that developers may unintentionally commit
+secrets and credentials to their remote repositories. If other people have access to the source,
+or if the project is public, the sensitive information is then exposed and can be leveraged by
+malicious users to gain access to resources like deployment environments.
+
+GitLab 11.9 includes a new check called Secret Detection. It scans the content of the repository
+to find API keys and other information that should not be there.
+
+GitLab displays identified secrets as part of the SAST reports visibly in a few places:
+
+- [Security Dashboard](../security_dashboard/)
+- Pipelines' **Security** tab
+- Report in the merge request widget
+
+![Secret Detection in merge request widget](img/secret-detection-merge-request-ui.png)
+
+## Use cases
+
+- Detecting accidental commit of secrets like keys, passwords, and API tokens.
+- Performing a single or recurring scan of the full history of your repository for secrets.
+
+## Configuration
+
+If you already have SAST enabled for your app, you don’t need to take any action to benefit from this
+new feature. It is also included in the Auto DevOps default configuration.
+
+Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L180)
+during the `sast` job. It runs regardless of the programming
+language of your app, and you don't need to change your
+CI/CD configuration file to enable it. Results are available in the SAST report.
+
+The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) checks.
+
+NOTE: **Note:**
+The Secret Detection analyzer will ignore "Password in URL" vulnerabilities if the password begins
+with a dollar sign (`$`) as this likely indicates the password being used is an environment
+variable. For example, `https://username:$password@example.com/path/to/repo` won't be
+detected, whereas `https://username:password@example.com/path/to/repo` would be detected.
+
+## Full History Secret Scan
+
+GitLab 12.11 introduced support for scanning the full history of a reposity. This new functionality
+is particularly useful when you are enabling Secret Detection in a repository for the first time and you
+want to perform a full secret scan. Running a secret scan on the full history can take a long time,
+especially for larger repositories with lengthy Git histories. We recommend not setting this variable
+as part of your normal job defintion.
+
+A new configuration variable ([`SAST_GITLEAKS_HISTORIC_SCAN`](../sast/#vulnerability-filters))
+can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository.
+
+We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret scan.
+<div class="video-fallback">
+  See the video: <a href="https://www.youtube.com/watch?v=wDtc_K00Y0A">Walkthrough of historical secret scan</a>.
+</div>
+<figure class="video-container">
+  <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe>
+</figure>
diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md
index e9d27fdbdd5..b8f9f043e38 100644
--- a/doc/user/group/epics/index.md
+++ b/doc/user/group/epics/index.md
@@ -11,19 +11,8 @@ Epics let you manage your portfolio of projects more efficiently and with less
 effort by tracking groups of issues that share a theme, across projects and
 milestones.
 
-## Relationships between epics and issues
-
-The possible relationships between epics and issues are:
-
-- An epic is the parent of one or more issues.
-- An epic is the parent of one or more child epics. For details see [Multi-level child epics](#multi-level-child-epics-ultimate). **(ULTIMATE)**
-
-```mermaid
-graph TD
-    Parent_epic --> Issue1
-    Parent_epic --> Child_epic
-    Child_epic --> Issue2
-```
+<!-- Possibly swap this file with one of a single epic -->
+![epics list view](img/epics_list_view_v12.5.png)
 
 ## Use cases
 
@@ -31,76 +20,36 @@ graph TD
 - Track when the work for the group of issues is targeted to begin, and when it's targeted to end.
 - Discuss and collaborate on feature ideas and scope at a high level.
 
-![epics list view](img/epics_list_view_v12.5.png)
-
-## Creating an epic
-
-A paginated list of epics is available in each group from where you can create
-a new epic. The list of epics includes also epics from all subgroups of the
-selected group. From your group page:
-
-1. Go to **Epics**.
-1. Click **New epic**.
-1. Enter a descriptive title and click **Create epic**.
-
-You will be taken to the new epic where can edit the following details:
-
-- Title
-- Description
-- Start date
-- Due date
-- Labels
-
-An epic's page contains the following tabs:
-
-- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are shown in a tree view.
-  - Click on the <kbd>></kbd> beside a parent epic to reveal the child epics and issues.
-  - Hover over the total counts to see a breakdown of open and closed items.
-- **Roadmap**: a roadmap view of child epics which have start and due dates.
-
-![epic view](img/epic_view_v13.0.png)
-
-## Adding an issue to an epic
-
-You can add an existing issue to an epic, or, from an epic's page, create a new issue that's automatically added to the epic.
-
-### Adding an existing issue to an epic
+## Manage epics
 
-Existing issues that belong to a project in an epic's group, or any of the epic's
-subgroups, are eligible to be added to the epic. Newly added issues appear at the top of the list of issues in the **Epics and Issues** tab.
+To learn what you can do with an epic, see [Manage epics](manage_epics.md). Possible actions include:
 
-An epic contains a list of issues and an issue can be associated with at most
-one epic. When you add an issue that's already linked to an epic,
-the issue is automatically unlinked from its current parent.
+- [Create an epic](manage_epics.md#create-an-epic)
+- [Bulk-edit epics](manage_epics.md#bulk-edit-epics)
+- [Delete an epic](manage_epics.md#delete-an-epic)
+- [Close an epic](manage_epics.md#close-an-epic)
+- [Reopen a closed epic](manage_epics.md#reopen-a-closed-epic)
+- [Go to an epic from an issue](manage_epics.md#go-to-an-epic-from-an-issue)
+- [Search for an epic from epics list page](manage_epics.md#search-for-an-epic-from-epics-list-page)
+- [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic)
+- [Manage multi-level child epics **(ULTIMATE)**](manage_epics.md#manage-multi-level-child-epics-ultimate)
 
-To add an issue to an epic:
-
-1. Click the **Add** dropdown button.
-1. Click **Add an issue**.
-1. Identify the issue to be added, using either of the following methods:
-   - Paste the link of the issue.
-   - Search for the desired issue by entering part of the issue's title, then selecting the desired match. ([From GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126))
-
-   If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step.
-1. Click **Add**.
-
-### Creating an issue from an epic
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5419) in GitLab 12.7.
-
-Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts.
+## Relationships between epics and issues
 
-To create an issue from an epic:
+The possible relationships between epics and issues are:
 
-1. On the epic's page, under **Epics and Issues**, click the **Add** dropdown button and select **Create new issue**.
-1. Under **Title**, enter the title for the new issue.
-1. From the **Project** dropdown, select the project in which the issue should be created.
-1. Click **Create issue**.
+- An epic is the parent of one or more issues.
+- An epic is the parent of one or more child epics. For details see [Multi-level child epics](#multi-level-child-epics-ultimate). **(ULTIMATE)**
 
-To remove an issue from an epic:
+```mermaid
+graph TD
+    Parent_epic --> Issue1
+    Parent_epic --> Child_epic
+    Child_epic --> Issue2
+```
 
-1. Click on the <kbd>x</kbd> button in the epic's issue list.
-1. Click **Remove** in the **Remove issue** warning message.
+See [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic) for steps
+to add an issue to an epic, reorder issues, move issues between epics, or promote an issue to an epic.
 
 ## Issue health status in Epic tree **(ULTIMATE)**
 
@@ -119,29 +68,15 @@ This feature comes with a feature flag enabled by default. For steps to disable
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8333) in GitLab Ultimate 11.7.
 
-Any epic that belongs to a group, or subgroup of the parent epic's group, is
-eligible to be added. New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
+Any epic that belongs to a group, or subgroup of the parent epic's group, is eligible to be added.
+New child epics appear at the top of the list of epics in the **Epics and Issues** tab.
 
 When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
 
-An epic can have multiple child epics with
-the maximum depth being 5.
-
-To add a child epic to an epic:
-
-1. Click the **Add** dropdown button.
-1. Click **Add an epic**.
-1. Identify the epic to be added, using either of the following methods:
-   - Paste the link of the epic.
-   - Search for the desired issue by entering part of the epic's title, then selecting the desired match. ([From GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126))
+An epic can have multiple child epics up to the maximum depth of five.
 
-   If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step.
-1. Click **Add**.
-
-To remove a child epic from a parent epic:
-
-1. Click on the <kbd>x</kbd> button in the parent epic's list of epics.
-1. Click **Remove** in the **Remove epic** warning message.
+See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics-ultimate) for
+steps to create, move, reorder, or delete child epics.
 
 ## Start date and due date
 
@@ -199,157 +134,6 @@ have a [start or due date](#start-date-and-due-date), a
 
 ![Child epics roadmap](img/epic_view_roadmap_v12_9.png)
 
----
-
-## Reordering issues and child epics
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5.
-
-New issues and child epics are added to the top of their respective lists in the **Epics and Issues**
-tab. You can reorder the list of issues and the list of child epics. Issues and child epics cannot
-be intermingled.
-
-To reorder issues assigned to an epic:
-
-1. Go to the **Epics and Issues** tab.
-1. Drag and drop issues into the desired order.
-
-To reorder child epics assigned to an epic:
-
-1. Go to the **Epics and Issues** tab.
-1. Drag and drop epics into the desired order.
-
-## Moving issues and child epics between epics
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0.
-
-New issues and child epics are added to the top of their respective lists in the **Epics and Issues**
-tab. You can move issues and child epics from one epic to another. Issues and child epics cannot
-be intermingled.
-
-To move an issue to another epic:
-
-1. Go to the **Epics and Issues** tab.
-1. Drag and drop issues into the desired parent epic.
-
-To move child epics to another epic:
-
-1. Go to the **Epics and Issues** tab.
-1. Drag and drop epics into the desired parent epic.
-
-## Updating epics
-
-### Using bulk editing
-
-To apply labels across multiple epics:
-
-1. Go to the Epics list.
-1. Click **Edit epics**.
-    - Checkboxes will appear beside each epic.
-    - A sidebar on the right-hand side will appear, with an editable field for labels.
-1. Check the checkbox beside each epic to be edited.
-1. Select the desired labels.
-1. Click **Update all**.
-
-![bulk editing](img/bulk_editing.png)
-
-## Deleting an epic
-
-NOTE: **Note:**
-To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup.
-
-When editing the description of an epic, click the **Delete** button to delete the epic.
-A modal will pop-up to confirm your action.
-
-Deleting an epic releases all existing issues from their associated epic in the
-system.
-
-## Closing and reopening epics
-
-### Using buttons
-
-Whenever you decide that there is no longer need for that epic,
-close the epic using the close button:
-
-![close epic - button](img/button_close_epic.png)
-
-You can always reopen it using the reopen button.
-
-![reopen epic - button](img/button_reopen_epic.png)
-
----
-
-### Using quick actions
-
-You can close or reopen an epic using [Quick actions](../../project/quick_actions.md)
-
-## Navigating to an epic from an issue
-
-If an issue belongs to an epic, you can navigate to the containing epic with the
-link in the issue sidebar.
-
-![containing epic](img/containing_epic.png)
-
----
-
-## Promoting an issue to an epic
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
-> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier.
-
-If you have [permissions](../../permissions.md) to close an issue and create an
-epic in the parent group, you can promote an issue to an epic with the `/promote`
-[quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics).
-Only issues from projects that are in groups can be promoted. When attempting to promote a confidential
-issue, a warning will display. Promoting a confidential issue to an epic will make all information
-related to the issue public as epics are public to group members.
-
-When the quick action is executed:
-
-- An epic is created in the same group as the project of the issue.
-- Subscribers of the issue are notified that the epic was created.
-
-The following issue metadata will be copied to the epic:
-
-- Title, description, activity/comment thread.
-- Upvotes/downvotes.
-- Participants.
-- Group labels that the issue already has.
-
-## Searching for an epic from epics list page
-
-> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5.
-> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier.
-
-You can search for an epic from the list of epics using filtered search bar (similar to
-that of Issues and Merge Requests) based on following parameters:
-
-- Title or description
-- Author name / username
-- Labels
-
-![epics search](img/epics_search.png)
-
-To search, go to the list of epics and click on the field **Search or filter results**.
-It will display a dropdown menu, from which you can add an author. You can also enter plain
-text to search by epic title or description. When done, press <kbd>Enter</kbd> on your
-keyboard to filter the list.
-
-You can also sort epics list by:
-
-- Created date
-- Last updated
-- Start date
-- Due date
-
-Each option contains a button that can toggle the order between **Ascending** and **Descending**.
-The sort option and order is saved and used wherever you browse epics, including the
-[Roadmap](../roadmap/index.md).
-
-![epics sort](img/epics_sort.png)
-
----
-
 ## Permissions
 
 If you have access to view an epic and have access to view an issue already
diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md
new file mode 100644
index 00000000000..8e2a47bb1af
--- /dev/null
+++ b/doc/user/group/epics/manage_epics.md
@@ -0,0 +1,272 @@
+---
+type: howto
+---
+
+<!-- When adding a new section here, remember to mention it in index.md#manage-epics -->
+
+# Manage epics **(PREMIUM)**
+
+This page collects instructions for all the things you can do with [epics](index.md) or in relation
+to them.
+
+## Create an epic
+
+A paginated list of epics is available in each group from where you can create
+a new epic. The list of epics includes also epics from all subgroups of the
+selected group. From your group page:
+
+1. Go to **Epics**.
+1. Click **New epic**.
+1. Enter a descriptive title and click **Create epic**.
+
+You will be taken to the new epic where can edit the following details:
+
+- Title
+- Description
+- Start date
+- Due date
+- Labels
+
+An epic's page contains the following tabs:
+
+- **Epics and Issues**: epics and issues added to this epic. Child epics and their issues appear in
+  a tree view.
+  - Click the <kbd>></kbd> beside a parent epic to reveal the child epics and issues.
+  - Hover over the total counts to see a breakdown of open and closed items.
+- **Roadmap**: a roadmap view of child epics which have start and due dates.
+
+![epic view](img/epic_view_v13.0.png)
+
+## Bulk-edit epics
+
+You can edit multiple epics at once. For example, to apply labels to multiple epics:
+
+1. Go to the Epics list.
+1. Click **Edit epics**.
+    - Checkboxes appear next to each epic.
+    - A sidebar on the right-hand side appears with an editable field for labels.
+1. Select the checkbox next to each epic to be edited.
+1. Select the labels you want.
+1. Click **Update all**.
+
+![bulk editing](img/bulk_editing.png)
+
+## Delete an epic
+
+NOTE: **Note:**
+To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup.
+
+When editing the description of an epic, click the **Delete** button to delete the epic.
+A modal appears to confirm your action.
+
+Deleting an epic releases all existing issues from their associated epic in the system.
+
+## Close an epic
+
+Whenever you decide that there is no longer need for that epic,
+close the epic by:
+
+- Clicking the **Close epic** button.
+
+  ![close epic - button](img/button_close_epic.png)
+
+- Using a [quick action](../../project/quick_actions.md).
+
+## Reopen a closed epic
+
+You can reopen an epic that was closed by:
+
+- Clicking the **Reopen epic** button.
+
+  ![reopen epic - button](img/button_reopen_epic.png)
+
+- Using a [quick action](../../project/quick_actions.md).
+
+## Go to an epic from an issue
+
+If an issue belongs to an epic, you can navigate to the containing epic with the
+link in the issue sidebar.
+
+![containing epic](img/containing_epic.png)
+
+## Search for an epic from epics list page
+
+> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5.
+> - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/37081) to the [Premium](https://about.gitlab.com/pricing/) tier in GitLab 12.8.
+
+You can search for an epic from the list of epics using filtered search bar (similar to
+that of Issues and Merge Requests) based on following parameters:
+
+- Title or description
+- Author name / username
+- Labels
+
+![epics search](img/epics_search.png)
+
+To search, go to the list of epics and click the field **Search or filter results**.
+It will display a dropdown menu, from which you can add an author. You can also enter plain
+text to search by epic title or description. When done, press <kbd>Enter</kbd> on your
+keyboard to filter the list.
+
+You can also sort epics list by:
+
+- Created date
+- Last updated
+- Start date
+- Due date
+
+Each option contains a button that can toggle the order between **Ascending** and **Descending**.
+The sort option and order is saved and used wherever you browse epics, including the
+[Roadmap](../roadmap/index.md).
+
+![epics sort](img/epics_sort.png)
+
+## Manage issues assigned to an epic
+
+### Add an issue to an epic
+
+You can add an existing issue to an epic, or, create a new issue that's
+automatically added to the epic.
+
+#### Add an existing issue to an epic
+
+Existing issues that belong to a project in an epic's group, or any of the epic's
+subgroups, are eligible to be added to the epic. Newly added issues appear at the top of the list of
+issues in the **Epics and Issues** tab.
+
+An epic contains a list of issues and an issue can be associated with at most one epic.
+When you add an issue that's already linked to an epic, the issue is automatically unlinked from its
+current parent.
+
+To add an issue to an epic:
+
+1. Click the **Add** dropdown button.
+1. Click **Add an issue**.
+1. Identify the issue to be added, using either of the following methods:
+   - Paste the link of the issue.
+   - Search for the desired issue by entering part of the issue's title, then selecting the desired
+     match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126)).
+
+   If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step.
+1. Click **Add**.
+
+#### Create an issue from an epic
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5419) in GitLab 12.7.
+
+Creating an issue from an epic enables you to maintain focus on the broader context of the epic
+while dividing work into smaller parts.
+
+To create an issue from an epic:
+
+1. On the epic's page, under **Epics and Issues**, click the **Add** dropdown button and select
+   **Create new issue**.
+1. Under **Title**, enter the title for the new issue.
+1. From the **Project** dropdown, select the project in which the issue should be created.
+1. Click **Create issue**.
+
+To remove an issue from an epic:
+
+1. Click the <kbd>x</kbd> button in the epic's issue list.
+1. Click **Remove** in the **Remove issue** warning message.
+
+### Reorder issues assigned to an epic
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5.
+
+New issues are added to the top of their list in the **Epics and Issues** tab.
+You can reorder the list of issues. Issues and child epics cannot be intermingled.
+
+To reorder issues assigned to an epic:
+
+1. Go to the **Epics and Issues** tab.
+1. Drag and drop issues into the desired order.
+
+To reorder child epics assigned to an epic:
+
+1. Go to the **Epics and Issues** tab.
+1. Drag and drop epics into the desired order.
+
+### Move issues between epics
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0.
+
+New issues are added to the top of their list in the **Epics and Issues**
+tab. You can move issues from one epic to another. Issues and child epics cannot be intermingled.
+
+To move an issue to another epic:
+
+1. Go to the **Epics and Issues** tab.
+1. Drag and drop issues into the desired parent epic.
+
+### Promote an issue to an epic
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
+> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier.
+
+If you have [permissions](../../permissions.md) to close an issue and create an
+epic in the parent group, you can promote an issue to an epic with the `/promote`
+[quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics).
+Only issues from projects that are in groups can be promoted. When attempting to promote a confidential
+issue, a warning will display. Promoting a confidential issue to an epic will make all information
+related to the issue public as epics are public to group members.
+
+When the quick action is executed:
+
+- An epic is created in the same group as the project of the issue.
+- Subscribers of the issue are notified that the epic was created.
+
+The following issue metadata will be copied to the epic:
+
+- Title, description, activity/comment thread.
+- Upvotes/downvotes.
+- Participants.
+- Group labels that the issue already has.
+
+## Manage multi-level child epics **(ULTIMATE)**
+
+### Add a child epic to an epic
+
+To add a child epic to an epic:
+
+1. Click the **Add** dropdown button.
+1. Click **Add an epic**.
+1. Identify the epic to be added, using either of the following methods:
+   - Paste the link of the epic.
+   - Search for the desired issue by entering part of the epic's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9126)).
+
+   If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step.
+1. Click **Add**.
+
+### Move child epics between epics
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0.
+
+New child epics are added to the top of their list in the **Epics and Issues** tab.
+You can move child epics from one epic to another.
+When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
+Issues and child epics cannot be intermingled.
+
+To move child epics **(ULTIMATE)** to another epic:
+
+1. Go to the **Epics and Issues** tab.
+1. Drag and drop epics into the desired parent epic.
+
+### Reorder child epics assigned to an epic
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5.
+
+New child epics are added to the top of their list in the **Epics and Issues** tab.
+You can reorder the list of child epics. Issues and child epics cannot be intermingled.
+
+To reorder child epics assigned to an epic:
+
+1. Go to the **Epics and Issues** tab.
+1. Drag and drop epics into the desired order.
+
+### Remove a child epic from a parent epic
+
+To remove a child epic from a parent epic:
+
+1. Click on the <kbd>x</kbd> button in the parent epic's list of epics.
+1. Click **Remove** in the **Remove epic** warning message.