Add latest changes from gitlab-org/gitlab@master

5 files changed, 97 insertions, 106 deletions

diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md
index b9637f1b6f5..54af9950bb1 100644
--- a/doc/administration/pages/index.md
+++ b/doc/administration/pages/index.md
@@ -373,9 +373,13 @@ When adding a custom domain, users are required to prove they own it by
 adding a GitLab-controlled verification code to the DNS records for that domain.
 
 If your user base is private or otherwise trusted, you can disable the
-verification requirement. Go to **Admin Area > Settings > Preferences** and
-uncheck **Require users to prove ownership of custom domains** in the **Pages** section.
-This setting is enabled by default.
+verification requirement:
+
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Settings > Preferences**.
+1. Expand **Pages**.
+1. Clear the **Require users to prove ownership of custom domains** checkbox.
+   This setting is enabled by default.
 
 ### Let's Encrypt integration
 
@@ -388,9 +392,11 @@ sites served under a custom domain.
 To enable it, you must:
 
 1. Choose an email address on which you want to receive notifications about expiring domains.
-1. Go to your instance's **Admin Area > Settings > Preferences** and expand **Pages** settings.
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Settings > Preferences**.
+1. Expand **Pages**.
 1. Enter the email address for receiving notifications and accept Let's Encrypt's Terms of Service as shown below.
-1. Click **Save changes**.
+1. Select **Save changes**.
 
 ![Let's Encrypt settings](img/lets_encrypt_integration_v12_1.png)
 
@@ -442,11 +448,12 @@ The scope to use for authentication must match the GitLab Pages OAuth applicatio
 pre-existing applications must modify the GitLab Pages OAuth application. Follow these steps to do
 this:
 
-1. Go to your instance's **Admin Area > Settings > Applications** and expand **GitLab Pages**
-   settings.
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Settings > Applications**.
+1. Expand **GitLab Pages**.
 1. Clear the `api` scope's checkbox and select the desired scope's checkbox (for example,
    `read_api`).
-1. Click **Save changes**.
+1. Select **Save changes**.
 
 #### Disabling public access to all Pages websites
 
@@ -460,9 +467,11 @@ This can be useful to preserve information published with Pages websites to the
 of your instance only.
 To do that:
 
-1. Go to your instance's **Admin Area > Settings > Preferences** and expand **Pages** settings.
-1. Check the **Disable public access to Pages sites** checkbox.
-1. Click **Save changes**.
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Settings > Preferences**.
+1. Expand **Pages**.
+1. Select the **Disable public access to Pages sites** checkbox.
+1. Select **Save changes**.
 
 WARNING:
 For self-managed installations, all public websites remain private until they are
@@ -635,12 +644,6 @@ Follow the steps below to configure the proxy listener of GitLab Pages.
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 
-## Set maximum pages size
-
-You can configure the maximum size of the unpacked archive per project in
-**Admin Area > Settings > Preferences > Pages**, in **Maximum size of pages (MB)**.
-The default is 100MB.
-
 ### Override maximum pages size per project or group **(PREMIUM SELF)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16610) in GitLab 12.7.
@@ -1256,9 +1259,14 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com
 
 ### The requested scope is invalid, malformed, or unknown
 
-This problem comes from the permissions of the GitLab Pages OAuth application. To fix it, go to
-**Admin > Applications > GitLab Pages** and edit the application. Under **Scopes**, ensure that the
-`api` scope is selected and save your changes.
+This problem comes from the permissions of the GitLab Pages OAuth application. To fix it:
+
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Applications > GitLab Pages**.
+1. Edit the application.
+1. Under **Scopes**, ensure that the `api` scope is selected.
+1. Save your changes.
+
 When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server),
 this setting needs to be configured on the main GitLab server.
 
diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md
index f1c3b515f68..1427713b9a4 100644
--- a/doc/administration/pages/source.md
+++ b/doc/administration/pages/source.md
@@ -443,9 +443,14 @@ are stored.
 
 ## Set maximum Pages size
 
-The maximum size of the unpacked archive per project can be configured in
-**Admin Area > Settings > Preferences > Pages**, in **Maximum size of pages (MB)**.
-The default is 100MB.
+The default for the maximum size of unpacked archives per project is 100 MB.
+
+To change this value:
+
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Settings > Preferences**.
+1. Expand **Pages**.
+1. Update the value for **Maximum size of pages (MB)**.
 
 ## Backup
 
diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md
index f4e384a2efb..75be51f5606 100644
--- a/doc/api/status_checks.md
+++ b/doc/api/status_checks.md
@@ -11,7 +11,7 @@ type: reference, api
 > - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default.
 > - It's disabled on GitLab.com.
 > - It's not recommended for production use.
-> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-status-checks). **(ULTIMATE SELF)**
+> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-external-status-checks).
  
 WARNING:
 This feature might not be available to you. Check the **version history** note above for details.
@@ -67,13 +67,6 @@ POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses
 NOTE:
 `sha` must be the SHA at the `HEAD` of the merge request's source branch.
 
-## Enable or disable status checks **(ULTIMATE SELF)**
-
-Status checks are under development and not ready for production use. It is
-deployed behind a feature flag that is **disabled by default**.
-[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md)
-can enable it.
-
 ## Get project external status checks **(ULTIMATE)**
 
 You can request information about a project's external status checks using the following endpoint:
@@ -86,7 +79,7 @@ GET /projects/:id/external_status_checks
 
 | Attribute           | Type    | Required | Description         |
 |---------------------|---------|----------|---------------------|
-| `id`                | integer | yes      | The ID of a project |
+| `id`                | integer | yes      | ID of a project     |
 
 ```json
 [
@@ -109,7 +102,7 @@ GET /projects/:id/external_status_checks
 ]
 ```
 
-### Create external status check **(ULTIMATE)**
+## Create external status check **(ULTIMATE)**
 
 You can create a new external status check for a project using the following endpoint:
 
@@ -117,14 +110,14 @@ You can create a new external status check for a project using the following end
 POST /projects/:id/external_status_checks
 ```
 
-| Attribute              | Type           | Required | Description                                        |
-|------------------------|----------------|----------|----------------------------------------------------|
-| `id`                   | integer        | yes      | The ID of a project                                |
-| `name`                 | string         | yes      | Display name of status check                      |
-| `external_url`         | string         | yes      | URL of status check resource                  |
-| `protected_branch_ids` | `array<Integer>` | no       | The ids of protected branches to scope the rule by |
+| Attribute              | Type             | Required | Description                                    |
+|------------------------|------------------|----------|------------------------------------------------|
+| `id`                   | integer          | yes      | ID of a project                                |
+| `name`                 | string           | yes      | Display name of status check                   |
+| `external_url`         | string           | yes      | URL of status check resource                   |
+| `protected_branch_ids` | `array<Integer>` | no       | IDs of protected branches to scope the rule by |
 
-### Delete external status check **(ULTIMATE)**
+## Delete external status check **(ULTIMATE)**
 
 You can delete an external status check for a project using the following endpoint:
 
@@ -132,12 +125,12 @@ You can delete an external status check for a project using the following endpoi
 DELETE /projects/:id/external_status_checks/:check_id
 ```
 
-| Attribute              | Type           | Required | Description                                        |
-|------------------------|----------------|----------|----------------------------------------------------|
-| `rule_id`              | integer        | yes      | The ID of an status check                         |
-| `id`                   | integer        | yes      | The ID of a project                                |
+| Attribute              | Type           | Required | Description           |
+|------------------------|----------------|----------|-----------------------|
+| `rule_id`              | integer        | yes      | ID of an status check |
+| `id`                   | integer        | yes      | ID of a project       |
 
-### Update external status check **(ULTIMATE)**
+## Update external status check **(ULTIMATE)**
 
 You can update an existing external status check for a project using the following endpoint:
 
@@ -145,18 +138,22 @@ You can update an existing external status check for a project using the followi
 PUT /projects/:id/external_status_checks/:check_id
 ```
 
-| Attribute              | Type           | Required | Description                                        |
-|------------------------|----------------|----------|----------------------------------------------------|
-| `id`                   | integer        | yes      | The ID of a project                                |
-| `rule_id`              | integer        | yes      | The ID of an external status check                |
-| `name`                 | string         | no       | Display name of status check                      |
-| `external_url`         | string         | no       | URL of external status check resource                  |
-| `protected_branch_ids` | `array<Integer>` | no       | The ids of protected branches to scope the rule by |
+| Attribute              | Type             | Required | Description                                    |
+|------------------------|------------------|----------|------------------------------------------------|
+| `id`                   | integer          | yes      | ID of a project                                |
+| `rule_id`              | integer          | yes      | ID of an external status check                 |
+| `name`                 | string           | no       | Display name of status check                   |
+| `external_url`         | string           | no       | URL of external status check resource          |
+| `protected_branch_ids` | `array<Integer>` | no       | IDs of protected branches to scope the rule by |
 
-### Enable or disable External Project-level MR status checks **(ULTIMATE SELF)**
+## Enable or disable external status checks **(ULTIMATE SELF)**
 
-Enable or disable External Project-level MR status checks is under development and not ready for production use. It is
-deployed behind a feature flag that is **disabled by default**.
+External status checks are:
+
+- Under development.
+- Not ready for production use.
+
+The feature is deployed behind a feature flag that is **disabled by default**.
 [GitLab administrators with access to the GitLab Rails console](../user/feature_flags.md)
 can enable it.
 
@@ -178,24 +175,6 @@ Feature.disable(:ff_compliance_approval_gates)
 Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>))
 ```
 
-To enable it:
-
-```ruby
-# For the instance
-Feature.enable(:ff_compliance_approval_gates)
-# For a single project
-Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>))
-```
-
-To disable it:
-
-```ruby
-# For the instance
-Feature.disable(:ff_compliance_approval_gates)
-# For a single project
-Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>)
-```
-
 ## Related links
 
-- [External status checks](../user/project/merge_requests/status_checks.md)
+- [External status checks](../user/project/merge_requests/status_checks.md).
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md
index 0778d598d32..3c9a796a9f2 100644
--- a/doc/ci/caching/index.md
+++ b/doc/ci/caching/index.md
@@ -19,62 +19,60 @@ Use cache for dependencies, like packages you download from the internet.
 Cache is stored where GitLab Runner is installed and uploaded to S3 if
 [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching).
 
-- You can define it per job by using the `cache:` keyword. Otherwise it is disabled.
-- You can define it per job so that:
-  - Subsequent pipelines can use it.
-  - Subsequent jobs in the same pipeline can use it, if the dependencies are identical.
-- You cannot share it between projects.
-
 Use artifacts to pass intermediate build results between stages.
 Artifacts are generated by a job, stored in GitLab, and can be downloaded.
 
-- You can define artifacts per job. Subsequent jobs in later stages of the same
-  pipeline can use them.
-- You can't use the artifacts in a different pipeline.
+Both artifacts and caches define their paths relative to the project directory, and
+can't link to files outside it.
+
+### Cache
+
+- Define cache per job by using the `cache:` keyword. Otherwise it is disabled.
+- Subsequent pipelines can use the cache.
+- Subsequent jobs in the same pipeline can use the cache, if the dependencies are identical.
+- Different projects cannot share the cache.
+
+### Artifacts
+
+- Define artifacts per job.
+- Subsequent jobs in later stages of the same pipeline can use artifacts.
+- Different projects cannot share artifacts.
 
 Artifacts expire after 30 days unless you define an [expiration time](../yaml/README.md#artifactsexpire_in).
 Use [dependencies](../yaml/README.md#dependencies) to control which jobs fetch the artifacts.
 
-Both artifacts and caches define their paths relative to the project directory, and
-can't link to files outside it.
-
 ## Good caching practices
 
-To ensure maximum availability of the cache, when you declare `cache` in your jobs,
-use one or more of the following:
+To ensure maximum availability of the cache, do one or more of the following:
 
 - [Tag your runners](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs
-  that share their cache.
+  that share the cache.
 - [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects).
-- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example,
-  different caches on each branch). For that, you can take advantage of the
-  [predefined CI/CD variables](../variables/README.md#predefined-cicd-variables).
+- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow. For example,
+  you can configure a different cache for each branch.
 
 For runners to work with caches efficiently, you must do one of the following:
 
 - Use a single runner for all your jobs.
-- Use multiple runners (in autoscale mode or not) that use
+- Use multiple runners that have
   [distributed caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching),
-  where the cache is stored in S3 buckets (like shared runners on GitLab.com).
-- Use multiple runners (not in autoscale mode) of the same architecture that
-  share a common network-mounted directory (using NFS or something similar)
-  where the cache is stored.
-
-Read about the [availability of the cache](#availability-of-the-cache)
-to learn more about the internals and get a better idea how cache works.
+  where the cache is stored in S3 buckets. Shared runners on GitLab.com behave this way. These runners can be in autoscale mode,
+  but they don't have to be. 
+- Use multiple runners with the same architecture and have these runners
+  share a common network-mounted directory to store the cache. This directory should use NFS or something similar.
+  These runners must be in autoscale mode. 
 
 ### Share caches between jobs in the same branch
 
-Define a cache with the `key: ${CI_COMMIT_REF_SLUG}` so that jobs of each
-branch always use the same cache:
+To have jobs for each branch use the same cache, define a cache with the `key: ${CI_COMMIT_REF_SLUG}`:
 
 ```yaml
 cache:
   key: ${CI_COMMIT_REF_SLUG}
 ```
 
-This configuration is safe from accidentally overwriting the cache, but merge requests
-get slow first pipelines. The next time a new commit is pushed to the branch, the
+This configuration prevents you from accidentally overwriting the cache. However, the
+first pipeline for a merge request is slow. The next time a commit is pushed to the branch, the
 cache is re-used and jobs run faster.
 
 To enable per-job and per-branch caching:
diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md
index c0bc97781b6..48959c0ba81 100644
--- a/doc/user/project/deploy_keys/index.md
+++ b/doc/user/project/deploy_keys/index.md
@@ -121,8 +121,9 @@ repositories to secure, shared services, such as CI/CD.
 
 Instance administrators can add public deploy keys:
 
-1. Go to **Admin Area > Deploy Keys**.
-1. Click on **New deploy key**.
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Deploy Keys**.
+1. Select **New deploy key**.
 
    Make sure your new key has a meaningful title, as it is the primary way for project
    maintainers and owners to identify the correct public deploy key to add. For example,