Add latest changes from gitlab-org/gitlab@master

6 files changed, 128 insertions, 128 deletions

diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt
index bf78eaaee8c..1cabfe303fa 100644
--- a/doc/.vale/gitlab/spelling-exceptions.txt
+++ b/doc/.vale/gitlab/spelling-exceptions.txt
@@ -101,6 +101,7 @@ failovers
 failsafe
 favicon
 firewalled
+Flawfinder
 Flowdock
 Fluentd
 Forgerock
@@ -112,9 +113,11 @@ Gitea
 GitHub
 GitLab
 gitlabsos
+Gitleaks
 Gitter
 Gmail
 Google
+Gosec
 Gradle
 Grafana
 gravatar
@@ -160,6 +163,7 @@ Kibana
 Knative
 Kramdown
 Kubernetes
+Kubesec
 Laravel
 LDAP
 Libravatar
@@ -302,12 +306,15 @@ sanitization
 serializer
 serializers
 serializing
+Sitespeed
 Slack
 Slony
 SMTP
+Sobelow
 Sourcegraph
 spidering
 Splunk
+SpotBugs
 SSH
 storable
 strace
diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql
index 79dd7a34c26..baf257eb2ff 100644
--- a/doc/api/graphql/reference/gitlab_schema.graphql
+++ b/doc/api/graphql/reference/gitlab_schema.graphql
@@ -9017,7 +9017,7 @@ type Snippet implements Noteable {
   httpUrlToRepo: String
 
   """
-  Id of the snippet
+  ID of the snippet
   """
   id: ID!
 
@@ -9463,7 +9463,7 @@ type Todo {
   group: Group
 
   """
-  Id of the todo
+  ID of the todo
   """
   id: ID!
 
diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json
index 7db78b5d34b..83809db6a9b 100644
--- a/doc/api/graphql/reference/gitlab_schema.json
+++ b/doc/api/graphql/reference/gitlab_schema.json
@@ -26985,7 +26985,7 @@
             },
             {
               "name": "id",
-              "description": "Id of the snippet",
+              "description": "ID of the snippet",
               "args": [
 
               ],
@@ -28412,7 +28412,7 @@
             },
             {
               "name": "id",
-              "description": "Id of the todo",
+              "description": "ID of the todo",
               "args": [
 
               ],
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
index 390e09a7cef..3259ce316e7 100644
--- a/doc/api/graphql/reference/index.md
+++ b/doc/api/graphql/reference/index.md
@@ -1365,7 +1365,7 @@ Represents a snippet entry
 | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
 | `fileName` | String | File Name of the snippet |
 | `httpUrlToRepo` | String | HTTP URL to the snippet repository |
-| `id` | ID! | Id of the snippet |
+| `id` | ID! | ID of the snippet |
 | `project` | Project | The project the snippet is associated with |
 | `rawUrl` | String! | Raw URL of the snippet |
 | `sshUrlToRepo` | String | SSH URL to the snippet repository |
@@ -1460,7 +1460,7 @@ Representing a todo entry
 | `body` | String! | Body of the todo |
 | `createdAt` | Time! | Timestamp this todo was created |
 | `group` | Group | Group this todo is associated with |
-| `id` | ID! | Id of the todo |
+| `id` | ID! | ID of the todo |
 | `project` | Project | The project this todo is associated with |
 | `state` | TodoStateEnum! | State of the todo |
 | `targetType` | TodoTargetEnum! | Target type of the todo |
diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md
index 0f42e062901..9299d096851 100644
--- a/doc/user/application_security/sast/index.md
+++ b/doc/user/application_security/sast/index.md
@@ -13,7 +13,7 @@ to learn how to protect your organization.
 
 ## Overview
 
-If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known
+If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known
 vulnerabilities using Static Application Security Testing (SAST).
 
 You can take advantage of SAST by doing one of the following:
@@ -37,7 +37,7 @@ The results are sorted by the priority of the vulnerability:
 1. Everything else
 
 NOTE: **Note:**
-A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure.
+A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard won't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard won't show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure.
 
 ## Use cases
 
@@ -55,12 +55,12 @@ executor running in privileged mode. If you're using the shared Runners on GitLa
 this is enabled by default.
 
 Privileged mode is not necessary if you've [disabled Docker in Docker
-for SAST](#disabling-docker-in-docker-for-sast)
+for SAST](#disabling-docker-in-docker-for-sast).
 
 CAUTION: **Caution:** Our SAST jobs currently expect a Linux container type. Windows containers are not yet supported.
 
 CAUTION: **Caution:**
-If you use your own Runners, make sure that the Docker version you have installed
+If you use your own Runners, make sure the Docker version installed
 is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details.
 
 ## Supported languages and frameworks
@@ -71,7 +71,7 @@ The following table shows which languages, package managers and frameworks are s
 |-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------|
 | .NET                                                                        | [Security Code Scan](https://security-code-scan.github.io)                             | 11.0                         |
 | Any                                                                         | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11.9    |
-| Apex (Salesforce)                                                           | [pmd](https://pmd.github.io/pmd/index.html)                                            | 12.1                         |
+| Apex (Salesforce)                                                           | [PMD](https://pmd.github.io/pmd/index.html)                                            | 12.1                         |
 | C/C++                                                                       | [Flawfinder](https://dwheeler.com/flawfinder/)                                         | 10.7                         |
 | Elixir (Phoenix)                                                            | [Sobelow](https://github.com/nccgroup/sobelow)                                         | 11.10                        |
 | Go                                                                          | [Gosec](https://github.com/securego/gosec)                                             | 10.7                         |
@@ -85,7 +85,7 @@ The following table shows which languages, package managers and frameworks are s
 | React                                                                       | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react)                | 12.5                         |
 | Ruby on Rails                                                               | [brakeman](https://brakemanscanner.org)                                                | 10.3                         |
 | Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) |
-| TypeScript                                                                  | [TSLint config security](https://github.com/webschik/tslint-config-security/)          | 11.9                         |
+| TypeScript                                                                  | [`tslint-config-security`](https://github.com/webschik/tslint-config-security/) | 11.9 |
 
 NOTE: **Note:**
 The Java analyzers can also be used for variants like the
@@ -104,7 +104,7 @@ provided by [Auto DevOps](../../../topics/autodevops/index.md).
 
 For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/README.md#includetemplate)
 the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml)
-that is provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you
+provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you
 can copy and use the job as defined that template.
 
 Add the following to your `.gitlab-ci.yml` file:
@@ -122,14 +122,13 @@ The results will be saved as a
 that you can later download and analyze. Due to implementation limitations, we
 always take the latest SAST artifact available. Behind the scenes, the
 [GitLab SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast)
-is used to detect the languages/frameworks and in turn runs the matching scan tools.
+is used to detect the languages or frameworks used, and in turn runs the matching scan tools.
 
 ### Customizing the SAST settings
 
 The SAST settings can be changed through [environment variables](#available-variables)
 by using the
 [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
-
 In the following example, we include the SAST template and at the same time we
 set the `SAST_GOSEC_LEVEL` variable to `2`:
 
@@ -142,7 +141,7 @@ variables:
 ```
 
 Because the template is [evaluated before](../../../ci/yaml/README.md#include)
-the pipeline configuration, the last mention of the variable will take precedence.
+the pipeline configuration, the last mention of the variable takes precedence.
 
 ### Overriding the SAST template
 
@@ -173,10 +172,10 @@ it via [custom environment variables](#custom-environment-variables).
 
 #### Using a variable to pass username and password to a private Maven repository
 
-If you have a private Maven repository which requires login credentials,
+If your private Maven repository requires login credentials,
 you can use the `MAVEN_CLI_OPTS` environment variable.
 
-Read more on [how to use private Maven repos](../index.md#using-private-maven-repos).
+Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos).
 
 ### Disabling Docker in Docker for SAST
 
@@ -198,11 +197,11 @@ to start relevant analyzers depending on the detected repository language(s) ins
 [orchestrator](https://gitlab.com/gitlab-org/security-products/dependency-scanning/). However, there
 are some differences in the way repository languages are detected between DIND and non-DIND. You can
 observe these differences by checking both Linguist and the common library. For instance, Linguist
-looks for `*.java` files to spin up the [spotbugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs)
+looks for `*.java` files to spin up the [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs)
 image, while orchestrator only looks for the existence of `pom.xml`, `build.xml`, `gradlew`,
-`grailsw`, or `mvnw`. GitLab uses Linguist to detect new file types in the default branch. This
-means that when introducing files or dependencies for a new language or package manager, the
-corresponding scans won't be triggered in the MR and will only run on the default branch once the
+`grailsw`, or `mvnw`. GitLab uses Linguist to detect new file types in the default branch.
+When introducing files or dependencies for a new language or package manager, the
+corresponding scans won't be triggered in the MR, and will only run on the default branch once the
 MR is merged. This will be addressed by [#211702](https://gitlab.com/gitlab-org/gitlab/-/issues/211702).
 
 NOTE: **Note:**
@@ -210,13 +209,13 @@ With the current language detection logic, any new languages or frameworks intro
 context of a merge request don't trigger a corresponding scan. These scans only occur once the code
 is committed to the default branch.
 
-#### Enabling kubesec analyzer
+#### Enabling Kubesec analyzer
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12752) in GitLab Ultimate 12.6.
 
 When [Docker in Docker is disabled](#disabling-docker-in-docker-for-sast),
 you will need to set `SCAN_KUBERNETES_MANIFESTS` to `"true"` to enable the
-kubesec analyzer. In `.gitlab-ci.yml`, define:
+Kubesec analyzer. In `.gitlab-ci.yml`, define:
 
 ```yaml
 include:
@@ -310,10 +309,10 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre
 | `SAST_BRAKEMAN_LEVEL`   |         1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. |
 | `SAST_FLAWFINDER_LEVEL` |         1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. |
 | `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. |
-| `SAST_GOSEC_LEVEL`      |         0 | Ignore gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. |
-| `SAST_GITLEAKS_COMMIT_FROM` | -     | The commit a gitleaks scan starts at. |
-| `SAST_GITLEAKS_COMMIT_TO` | -       | The commit a gitleaks scan ends at. |
-| `SAST_GITLEAKS_HISTORIC_SCAN` | false | Flag to enable a historic gitleaks scan. |
+| `SAST_GOSEC_LEVEL`      |         0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. |
+| `SAST_GITLEAKS_COMMIT_FROM` | -     | The commit a Gitleaks scan starts at. |
+| `SAST_GITLEAKS_COMMIT_TO` | -       | The commit a Gitleaks scan ends at. |
+| `SAST_GITLEAKS_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. |
 
 #### Docker-in-Docker orchestrator
 
@@ -323,9 +322,9 @@ The following variables configure the Docker-in-Docker orchestrator.
 |------------------------------------------|---------------|-------------|
 | `SAST_ANALYZER_IMAGES`                   |         |  Comma-separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). Not available when [Docker-in-Docker is disabled](#disabling-docker-in-docker-for-sast). |
 | `SAST_PULL_ANALYZER_IMAGES`              |       1 | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). Not available when [Docker-in-Docker is disabled](#disabling-docker-in-docker-for-sast).          |
-| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` |      2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". |
-| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT`       |      5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". |
-| `SAST_RUN_ANALYZER_TIMEOUT`              |     20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m".|
+| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` |      2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. |
+| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT`       |      5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. |
+| `SAST_RUN_ANALYZER_TIMEOUT`              |     20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`.|
 
 NOTE: **Note:**
 Timeout variables are not applicable for setups with [disabled Docker In Docker](index.md#disabling-docker-in-docker-for-sast).
@@ -336,18 +335,18 @@ Some analyzers can be customized with environment variables.
 
 | Environment variable        | Analyzer | Description |
 |-----------------------------|----------|-------------|
-| `SCAN_KUBERNETES_MANIFESTS` | kubesec  | Set to `"true"` to scan Kubernetes manifests when [Docker in Docker](#disabling-docker-in-docker-for-sast) is disabled. |
-| `ANT_HOME`                  | spotbugs | The `ANT_HOME` environment variable. |
-| `ANT_PATH`                  | spotbugs | Path to the `ant` executable. |
-| `GRADLE_PATH`               | spotbugs | Path to the `gradle` executable. |
-| `JAVA_OPTS`                 | spotbugs | Additional arguments for the `java` executable. |
-| `JAVA_PATH`                 | spotbugs | Path to the `java` executable. |
-| `SAST_JAVA_VERSION`         | spotbugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. |
-| `MAVEN_CLI_OPTS`            | spotbugs | Additional arguments for the `mvn` or `mvnw` executable. |
-| `MAVEN_PATH`                | spotbugs | Path to the `mvn` executable. |
-| `MAVEN_REPO_PATH`           | spotbugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). |
-| `SBT_PATH`                  | spotbugs | Path to the `sbt` executable. |
-| `FAIL_NEVER`                | spotbugs | Set to `1` to ignore compilation failure. |
+| `SCAN_KUBERNETES_MANIFESTS` | Kubesec  | Set to `"true"` to scan Kubernetes manifests when [Docker in Docker](#disabling-docker-in-docker-for-sast) is disabled. |
+| `ANT_HOME`                  | SpotBugs | The `ANT_HOME` environment variable. |
+| `ANT_PATH`                  | SpotBugs | Path to the `ant` executable. |
+| `GRADLE_PATH`               | SpotBugs | Path to the `gradle` executable. |
+| `JAVA_OPTS`                 | SpotBugs | Additional arguments for the `java` executable. |
+| `JAVA_PATH`                 | SpotBugs | Path to the `java` executable. |
+| `SAST_JAVA_VERSION`         | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. |
+| `MAVEN_CLI_OPTS`            | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. |
+| `MAVEN_PATH`                | SpotBugs | Path to the `mvn` executable. |
+| `MAVEN_REPO_PATH`           | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). |
+| `SBT_PATH`                  | SpotBugs | Path to the `sbt` executable. |
+| `FAIL_NEVER`                | SpotBugs | Set to `1` to ignore compilation failure. |
 
 #### Custom environment variables
 
@@ -454,8 +453,8 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
 | `version`                               | Report syntax version used to generate this JSON. |
 | `vulnerabilities`                       | Array of vulnerability objects. |
 | `vulnerabilities[].id`                  | Unique identifier of the vulnerability. |
-| `vulnerabilities[].category`            | Where this vulnerability belongs (SAST, Dependency Scanning etc.). For SAST, it will always be `sast`. |
-| `vulnerabilities[].name`                | Name of the vulnerability, this must not include the occurrence's specific information. Optional. |
+| `vulnerabilities[].category`            | Where this vulnerability belongs (such as SAST, Dependency Scanning). For SAST, it will always be `sast`. |
+| `vulnerabilities[].name`                | Name of the vulnerability. Must not include the occurrence's specific information. Optional. |
 | `vulnerabilities[].message`             | A short text that describes the vulnerability, it may include the occurrence's specific information. Optional. |
 | `vulnerabilities[].description`         | A long text that describes the vulnerability. Optional. |
 | `vulnerabilities[].cve`                 | (**DEPRECATED - use `vulnerabilities[].id` instead**) A fingerprint string value that represents a concrete occurrence of the vulnerability. It's used to determine whether two vulnerability occurrences are same or different. May not be 100% accurate. **This is NOT a [CVE](https://cve.mitre.org/)**.                                                                                                                                      |
@@ -471,8 +470,8 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
 | `vulnerabilities[].location.end_line`   | The last line of the code affected by the vulnerability. Optional. |
 | `vulnerabilities[].location.class`      | If specified, provides the name of the class where the vulnerability is located. Optional. |
 | `vulnerabilities[].location.method`     | If specified, provides the name of the method where the vulnerability is located. Optional. |
-| `vulnerabilities[].identifiers`         | An ordered array of references that identify a vulnerability on internal or external DBs. |
-| `vulnerabilities[].identifiers[].type`  | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (e.g., `bandit_test_id` for [Bandit analyzer](https://wiki.openstack.org/wiki/Security/Projects/Bandit)). |
+| `vulnerabilities[].identifiers`         | An ordered array of references that identify a vulnerability on internal or external databases. |
+| `vulnerabilities[].identifiers[].type`  | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (like `bandit_test_id` for [Bandit analyzer](https://wiki.openstack.org/wiki/Security/Projects/Bandit)). |
 | `vulnerabilities[].identifiers[].name`  | Name of the identifier for display purposes. |
 | `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purposes. |
 | `vulnerabilities[].identifiers[].url`   | URL to identifier's documentation. Optional. |
@@ -480,8 +479,8 @@ 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 (for example, an API key that allows write access to third-party deployment
-environments).
+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
@@ -492,7 +491,7 @@ GitLab currently includes [Gitleaks](https://github.com/zricethezav/gitleaks) an
 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` will not be
+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.
 
 ## Security Dashboard
@@ -515,13 +514,13 @@ For more information about the vulnerabilities database update, check the
 
 For self-managed GitLab instances in an environment with limited, restricted, or intermittent access
 to external resources through the internet, some adjustments are required for the SAST job to
-successfully run. For more information, see [Offline environments](../offline_deployments/index.md).
+run successfully. For more information, see [Offline environments](../offline_deployments/index.md).
 
 ### Requirements for offline SAST
 
 To use SAST in an offline environment, you need:
 
-- [Disable Docker-In-Docker](#disabling-docker-in-docker-for-sast)
+- To [disable Docker-In-Docker](#disabling-docker-in-docker-for-sast).
 - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements).
 - Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images.
 
@@ -560,7 +559,7 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/tslint:2
 The process for importing Docker images into a local offline Docker registry depends on
 **your network security policy**. Please consult your IT staff to find an accepted and approved
 process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
-with new definitions, so consider if you are able to make periodic updates yourself.
+with new definitions, so consider if you're able to make periodic updates yourself.
 
 For details on saving and transporting Docker images as a file, see Docker's documentation on
 [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
@@ -588,6 +587,6 @@ security reports without requiring internet access.
 ### Error response from daemon: error processing tar file: docker-tar: relocation error
 
 This error occurs when the Docker version used to run the SAST job is `19.03.0`.
-You are advised to update to Docker `19.03.1` or greater. Older versions are not
+Consider updating to Docker `19.03.1` or greater. Older versions are not
 affected. Read more in
 [this issue](https://gitlab.com/gitlab-org/gitlab/issues/13830#note_211354992 "Current SAST container fails").
diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md
index 3dd87fcc8f5..b76c6397204 100644
--- a/doc/user/project/merge_requests/browser_performance_testing.md
+++ b/doc/user/project/merge_requests/browser_performance_testing.md
@@ -6,55 +6,50 @@ type: reference, howto
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3507) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3.
 
-If your application offers a web interface and you are using
+If your application offers a web interface and you're using
 [GitLab CI/CD](../../../ci/README.md), you can quickly determine the performance
 impact of pending code changes.
 
 ## Overview
 
 GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source
-tool for measuring the performance of web sites, and has built a simple
-[Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance)
-which outputs the results in a file called `performance.json`. This plugin
-outputs the performance score for each page that is analyzed.
-
+tool, for measuring the performance of web sites. GitLab has built a simple
+[Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance) which outputs
+the performance score for each page analyzed in a file called `performance.json`.
 The [Sitespeed.io performance score](https://examples.sitespeed.io/6.0/2017-11-23-23-43-35/help.html)
-is a composite value based on best practices, and we will be expanding support
-for [additional metrics](https://gitlab.com/gitlab-org/gitlab/issues/4370)
-in a future release.
+is a composite value based on best practices.
 
-Going a step further, GitLab can show the Performance report right
-in the merge request widget area (see below).
+GitLab can [show the Performance report](#how-browser-performance-testing-works)
+in the merge request widget area.
 
 ## Use cases
 
-For instance, consider the following workflow:
+Consider the following workflow:
 
 1. A member of the marketing team is attempting to track engagement by adding a new tool.
 1. With browser performance metrics, they see how their changes are impacting the usability
    of the page for end users.
-1. The metrics show that after their changes the performance score of the page has gone down.
-1. When looking at the detailed report, they see that the new JavaScript library was
-   included in `<head>` which affects loading page speed.
-1. They ask a front end developer to help them, who sets the library to load asynchronously.
-1. The frontend developer approves the merge request and authorizes its deployment to production.
+1. The metrics show that after their changes, the performance score of the page has gone down.
+1. When looking at the detailed report, they see the new JavaScript library was
+   included in `<head>`, which affects loading page speed.
+1. They ask for help from a front end developer, who sets the library to load asynchronously.
+1. The frontend developer approves the merge request, and authorizes its deployment to production.
 
-## How it works
+## How browser performance testing works
 
-First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the
+First, define a job in your `.gitlab-ci.yml` file that generates the
 [Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium).
-For more information on how the Performance job should look like, check the
-example on [Configuring Browser Performance Testing](#configuring-browser-performance-testing).
-
 GitLab then checks this report, compares key performance metrics for each page
-between the source and target branches, and shows the information right on the merge request.
+between the source and target branches, and shows the information in the merge request.
+
+For an example Performance job, see
+[Configuring Browser Performance Testing](#configuring-browser-performance-testing).
 
 NOTE: **Note:**
-If the Performance report doesn't have anything to compare to, no information
-will be displayed in the merge request area. That is the case when you add the
-Performance job in your `.gitlab-ci.yml` for the very first time.
-Consecutive merge requests will have something to compare to, and the Performance
-report will be shown properly.
+If the Performance report has no data to compare, such as when you add the
+Performance job in your `.gitlab-ci.yml` for the very first time, no information
+displays in the merge request widget area. Consecutive merge requests will have data for
+comparison, and the Performance report will be shown properly.
 
 ![Performance Widget](img/browser_performance_testing.png)
 
@@ -64,52 +59,51 @@ This example shows how to run the [sitespeed.io container](https://hub.docker.co
 on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io)
 using Docker-in-Docker.
 
-First, you need GitLab Runner with
-[docker-in-docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor).
+1. First, set up GitLab Runner with a
+   [docker-in-docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor).
+1. After configuring the Runner, add a new job to `.gitlab-ci.yml` that generates
+   the expected report.
+1. Define the `performance` job according to your version of GitLab:
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that generates the
-expected report.
+   - For GitLab 12.4 and later - [include](../../../ci/yaml/README.md#includetemplate) the
+     [`Browser-Performance.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml) provided as a part of your GitLab installation.
+   - For GitLab versions earlier than 12.4 - Copy and use the job as defined in the
+     [`Browser-Performance.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml).
 
-For GitLab 12.4 and later, to define the `performance` job, you must
-[include](../../../ci/yaml/README.md#includetemplate) the
-[`Browser-Performance.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml)
-that's provided as a part of your GitLab installation.
-For GitLab versions earlier than 12.4, you can copy and use the job as defined
-in that template.
+   CAUTION: **Caution:**
+   The job definition provided by the template does not support Kubernetes yet.
+   For a complete example of a more complex setup that works in Kubernetes, see
+   [`Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml).
 
-CAUTION: **Caution:**
-The job definition provided by the template does not support Kubernetes yet. For a complete example of a more complex setup
-that works in Kubernetes, see [here](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml).
+1. Add the following to your `.gitlab-ci.yml` file:
 
-Add the following to your `.gitlab-ci.yml` file:
+   ```yaml
+   include:
+     template: Verify/Browser-Performance.gitlab-ci.yml
 
-```yaml
-include:
-  template: Verify/Browser-Performance.gitlab-ci.yml
+   performance:
+     variables:
+       URL: https://example.com
+   ```
 
-performance:
-  variables:
-    URL: https://example.com
-```
-
-CAUTION: **Caution:**
-The job definition provided by the template is supported in GitLab 11.5 and later versions.
-It also requires GitLab Runner 11.5 or later. For earlier versions, use the
-[previous job definitions](#previous-job-definitions).
+   CAUTION: **Caution:**
+   The job definition provided by the template is supported in GitLab 11.5 and later versions.
+   It also requires GitLab Runner 11.5 or later. For earlier versions, use the
+   [previous job definitions](#previous-job-definitions).
 
-The above example will create a `performance` job in your CI/CD pipeline and will run
+The above example creates a `performance` job in your CI/CD pipeline and runs
 sitespeed.io against the webpage you defined in `URL` to gather key metrics.
 The [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance)
-is downloaded in order to save the report as a [Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium)
-that you can later download and analyze. Due to implementation limitations we always
+is downloaded to save the report as a [Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium)
+that you can later download and analyze. Due to implementation limitations, we always
 take the latest Performance artifact available.
 
-The full HTML sitespeed.io report will also be saved as an artifact, and if you have
-[GitLab Pages](../pages/index.md) enabled, it can be viewed directly in your browser.
+The full HTML sitespeed.io report is saved as an artifact, and if
+[GitLab Pages](../pages/index.md) is enabled, it can be viewed directly in your browser.
 
-It is also possible to customize options by setting the `SITESPEED_OPTIONS` variable.
-For example, this is how to override the number of runs sitespeed.io
-will make on the given URL:
+You can also customize options by setting the `SITESPEED_OPTIONS` variable.
+For example, you can override the number of runs sitespeed.io
+makes on the given URL:
 
 ```yaml
 include:
@@ -122,7 +116,8 @@ performance:
 ```
 
 For further customization options for sitespeed.io, including the ability to provide a
-list of URLs to test, please see the [Sitespeed.io Configuration](https://www.sitespeed.io/documentation/sitespeed.io/configuration/)
+list of URLs to test, please see the
+[Sitespeed.io Configuration](https://www.sitespeed.io/documentation/sitespeed.io/configuration/)
 documentation.
 
 TIP: **Tip:**
@@ -130,19 +125,18 @@ Key metrics are automatically extracted and shown in the merge request widget.
 
 ### Performance testing on Review Apps
 
-The above CI YML is great for testing against static environments, and it can
-be extended for dynamic environments. There are a few extra steps to take to
-set this up:
+The above CI YAML configuration is great for testing against static environments, and it can
+be extended for dynamic environments, but a few extra steps are required:
 
 1. The `performance` job should run after the dynamic environment has started.
 1. In the `review` job, persist the hostname and upload it as an artifact so
-   it's available to the `performance` job (the same can be done for static
-   environments like staging and production to unify the code path). Saving it
-   as an artifact is as simple as `echo $CI_ENVIRONMENT_URL > environment_url.txt`
+   it's available to the `performance` job. The same can be done for static
+   environments like staging and production to unify the code path. You can save it
+   as an artifact with `echo $CI_ENVIRONMENT_URL > environment_url.txt`
    in your job's `script`.
 1. In the `performance` job, read the previous artifact into an environment
-   variable, in this case `$URL` because this is what our sitespeed.io command
-   uses for the URL parameter. Because Review App URLs are dynamic, we define
+   variable. In this case, use `$URL` because the sitespeed.io command
+   uses it for the URL parameter. Because Review App URLs are dynamic, define
    the `URL` variable through `before_script` instead of `variables`.
 1. You can now run the sitespeed.io container against the desired hostname and
    paths.
@@ -183,11 +177,11 @@ performance:
 ### Previous job definitions
 
 CAUTION: **Caution:**
-Before GitLab 11.5, Performance job and artifact had to be named specifically
+Before GitLab 11.5, the Performance job and artifact had to be named specifically
 to automatically extract report data and show it in the merge request widget.
-While these old job definitions are still maintained they have been deprecated
+While these old job definitions are still maintained, they have been deprecated
 and may be removed in next major release, GitLab 12.0.
-You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change.
+GitLab recommends you update your current `.gitlab-ci.yml` configuration to reflect that change.
 
 For GitLab 11.4 and earlier, the job should look like: