Add latest changes from gitlab-org/gitlab@master

19 files changed, 217 insertions, 141 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 45cf56df894..a363721bd73 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -96,6 +96,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy
 | [Cache dependencies](caching/index.md)                  | Cache your dependencies for a faster execution.                                |
 | [GitLab Runner](https://docs.gitlab.com/runner/)        | Configure your own runners to execute your scripts.                            |
 | [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and efficiently.                       |
+| [Test cases](test_cases/index.md) | Configure your pipelines to run quickly and efficiently.                       |
 
 ## Configuration
 
@@ -121,38 +122,38 @@ Note that certain operations can only be performed according to the
 Use the vast GitLab CI/CD to easily configure it for specific purposes.
 Its feature set is listed on the table below according to DevOps stages.
 
-| Feature | Description |
-|:--------|:------------|
-| **Configure** ||
-| [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. |
-| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. |
-|---+---|
-| **Verify** ||
-| [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. |
-| [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. |
-| [CI services](services/README.md) | Link Docker containers with your base image.|
-| [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. |
-| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. |
-| [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)** | Open an interactive web terminal to debug the running jobs. |
-| [Unit test reports](unit_test_reports.md) | Identify script failures directly on merge requests. |
-| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. |
-|---+---|
-| **Release** ||
-| [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. |
-| [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. |
-| [Canary Deployments](../user/project/canary_deployments.md) **(PREMIUM)** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. |
-| [Deploy Boards](../user/project/deploy_boards.md) **(PREMIUM)** | Check the current health and status of each CI/CD environment running on Kubernetes. |
-| [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. |
-| [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. |
-| [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. |
-| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. |
-| [Cloud deployment](cloud_deployment/index.md) | Deploy your application to a main cloud provider. |
-|---+---|
-| **Secure** ||
-| [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities.|
-| [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. |
-| [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. |
-| [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. |
+| Feature                                                                                         | Description                                                                                                                    |
+|:------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------|
+| **Configure**                                                                                   |                                                                                                                                |
+| [Auto DevOps](../topics/autodevops/index.md)                                                    | Set up your app's entire lifecycle.                                                                                            |
+| [ChatOps](chatops/README.md)                                                                    | Trigger CI jobs from chat, with results sent back to the channel.                                                              |
+|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------|
+| **Verify**                                                                                      |                                                                                                                                |
+| [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md)    | Quickly determine the browser performance impact of pending code changes.                                                      |
+| [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md)          | Quickly determine the server performance impact of pending code changes.                                                       |
+| [CI services](services/README.md)                                                               | Link Docker containers with your base image.                                                                                   |
+| [Code Quality](../user/project/merge_requests/code_quality.md)                                  | Analyze your source code quality.                                                                                              |
+| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)**       | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud.                                     |
+| [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)**                  | Open an interactive web terminal to debug the running jobs.                                                                    |
+| [Unit test reports](unit_test_reports.md)                                                       | Identify script failures directly on merge requests.                                                                           |
+| [Using Docker images](docker/using_docker_images.md)                                            | Use GitLab and GitLab Runner with Docker to build and test applications.                                                       |
+|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------|
+| **Release**                                                                                     |                                                                                                                                |
+| [Auto Deploy](../topics/autodevops/stages.md#auto-deploy)                                       | Deploy your application to a production environment in a Kubernetes cluster.                                                   |
+| [Building Docker images](docker/using_docker_build.md)                                          | Maintain Docker-based projects using GitLab CI/CD.                                                                             |
+| [Canary Deployments](../user/project/canary_deployments.md) **(PREMIUM)**                       | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. |
+| [Deploy Boards](../user/project/deploy_boards.md) **(PREMIUM)**                                 | Check the current health and status of each CI/CD environment running on Kubernetes.                                           |
+| [Feature Flags](../operations/feature_flags.md) **(PREMIUM)**                                   | Deploy your features behind Feature Flags.                                                                                     |
+| [GitLab Pages](../user/project/pages/index.md)                                                  | Deploy static websites.                                                                                                        |
+| [GitLab Releases](../user/project/releases/index.md)                                            | Add release notes to Git tags.                                                                                                 |
+| [Review Apps](review_apps/index.md)                                                             | Configure GitLab CI/CD to preview code changes.                                                                                |
+| [Cloud deployment](cloud_deployment/index.md)                                                   | Deploy your application to a main cloud provider.                                                                              |
+|-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------|
+| **Secure**                                                                                      |                                                                                                                                |
+| [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)**   | Check your Docker containers for known vulnerabilities.                                                                        |
+| [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities.                                                                           |
+| [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)**             | Search your project dependencies for their licenses.                                                                           |
+| [Security Test reports](../user/application_security/index.md) **(ULTIMATE)**                   | Check for app vulnerabilities.                                                                                                 |
 
 ## Examples
 
diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md
index 8b88ec509e7..189281635fd 100644
--- a/doc/ci/enable_or_disable_ci.md
+++ b/doc/ci/enable_or_disable_ci.md
@@ -31,7 +31,7 @@ either:
 - Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source
   and Omnibus installations respectively.
 
-This only applies to pipelines run as part of GitLab CI/CD. This will not enable or disable
+This only applies to pipelines run as part of GitLab CI/CD. This doesn't enable or disable
 pipelines that are run from an [external integration](../user/project/integrations/overview.md#integrations-listing).
 
 ## Per-project user setting
@@ -42,7 +42,7 @@ To enable or disable GitLab CI/CD Pipelines in your project:
 1. Expand the **Repository** section
 1. Enable or disable the **Pipelines** toggle as required.
 
-**Project visibility** will also affect pipeline visibility. If set to:
+**Project visibility** also affects pipeline visibility. If set to:
 
 - **Private**: Only project members can access pipelines.
 - **Internal** or **Public**: Pipelines can be set to either **Only Project Members**
@@ -57,9 +57,9 @@ for source installations, and `gitlab.rb` for Omnibus installations.
 
 Two things to note:
 
-- Disabling GitLab CI/CD, will affect only newly-created projects. Projects that
-  had it enabled prior to this modification, will work as before.
-- Even if you disable GitLab CI/CD, users will still be able to enable it in the
+- Disabling GitLab CI/CD affects only newly-created projects. Projects that
+  had it enabled prior to this modification work as before.
+- Even if you disable GitLab CI/CD, users can still enable it in the
   project's settings.
 
 For installations from source, open `gitlab.yml` with your editor and set
diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md
index c28febd15d7..48434c02dfd 100644
--- a/doc/ci/git_submodules.md
+++ b/doc/ci/git_submodules.md
@@ -21,7 +21,7 @@ type: reference
 
 ## Configuring the `.gitmodules` file
 
-If dealing with [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), your project will probably have a file
+If dealing with [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), your project probably has a file
 named `.gitmodules`.
 
 Let's consider the following example:
@@ -44,11 +44,11 @@ for all your local checkouts. The `.gitmodules` would look like:
   url = ../../group/project.git
 ```
 
-The above configuration will instruct Git to automatically deduce the URL that
-should be used when cloning sources. Whether you use HTTP(S) or SSH, Git will use
-that same channel and it will allow to make all your CI jobs use HTTP(S)
-(because GitLab CI/CD only uses HTTP(S) for cloning your sources), and all your local
-clones will continue using SSH.
+The above configuration instructs Git to automatically deduce the URL that
+should be used when cloning sources. Whether you use HTTP(S) or SSH, Git uses
+that same channel and it makes all your CI jobs use HTTP(S).
+GitLab CI/CD only uses HTTP(S) for cloning your sources, and all your local
+clones continue using SSH.
 
 For all other submodules not located on the same GitLab server, use the full
 HTTP(S) protocol URL:
@@ -94,7 +94,7 @@ correctly with your CI jobs:
    whether you have recursive submodules.
 
 The rationale to set the `sync` and `update` in `before_script` is because of
-the way Git submodules work. On a fresh runner workspace, Git will set the
+the way Git submodules work. On a fresh runner workspace, Git sets the
 submodule URL including the token in `.git/config`
 (or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current
 remote URL. On subsequent jobs on the same runner, `.git/config` is cached
diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md
index dbc0397bb0b..d66ab2b297a 100644
--- a/doc/ci/metrics_reports.md
+++ b/doc/ci/metrics_reports.md
@@ -11,7 +11,7 @@ type: reference
 
 GitLab provides a lot of great reporting tools for [merge requests](../user/project/merge_requests/index.md) - [Unit test reports](unit_test_reports.md), [code quality](../user/project/merge_requests/code_quality.md), performance tests, etc. While JUnit is a great open framework for tests that "pass" or "fail", it is also important to see other types of metrics from a given change.
 
-You can configure your job to use custom Metrics Reports, and GitLab will display a report on the merge request so that it's easier and faster to identify changes without having to check the entire log.
+You can configure your job to use custom Metrics Reports, and GitLab displays a report on the merge request so that it's easier and faster to identify changes without having to check the entire log.
 
 ![Metrics Reports](img/metrics_reports_v13_0.png)
 
diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md
index 13190c15cca..5bb8e76831a 100644
--- a/doc/ci/migration/circleci.md
+++ b/doc/ci/migration/circleci.md
@@ -200,7 +200,7 @@ deploy_prod:
 
 ### Filter job by branch
 
-[Rules](../yaml/README.md#rules) are a mechanism to determine if the job will or will not run for a specific branch.
+[Rules](../yaml/README.md#rules) are a mechanism to determine if the job runs for a specific branch.
 
 CircleCI example of a job filtered by branch:
 
diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md
index afec94ca91c..19df310d1a2 100644
--- a/doc/ci/migration/jenkins.md
+++ b/doc/ci/migration/jenkins.md
@@ -33,7 +33,7 @@ For an example of how to convert a Jenkins pipeline into a GitLab CI/CD pipeline
 or how to use Auto DevOps to test your code automatically, watch the
 [Migrating from Jenkins to GitLab](https://www.youtube.com/watch?v=RlEVGOpYF5Y) video.
 
-Otherwise, read on for important information that will help you get the ball rolling. Welcome
+Otherwise, read on for important information that helps you get the ball rolling. Welcome
 to GitLab!
 
 If you have questions that are not answered here, the [GitLab community forum](https://forum.gitlab.com/)
@@ -46,22 +46,22 @@ changes that comes with the move, and successfully managing them. There are a fe
 things we have found that helps this:
 
 - Setting and communicating a clear vision of what your migration goals are helps
-  your users understand why the effort is worth it. The value will be clear when
+  your users understand why the effort is worth it. The value is clear when
   the work is done, but people need to be aware while it's in progress too.
 - Sponsorship and alignment from the relevant leadership team helps with the point above.
 - Spending time educating your users on what's different, sharing this document with them,
-  and so on will help ensure you are successful.
+  and so on helps ensure you are successful.
 - Finding ways to sequence or delay parts of the migration can help a lot, but you
   don't want to leave things in a non-migrated (or partially-migrated) state for too
   long. To gain all the benefits of GitLab, moving your existing Jenkins setup over
-  as-is, including any current problems, will not be enough. You need to take advantage
+  as-is, including any current problems, isn't enough. You need to take advantage
   of the improvements that GitLab offers, and this requires (eventually) updating
   your implementation as part of the transition.
 
 ## JenkinsFile Wrapper
 
-We are building a [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/) which will allow
-you to run a complete Jenkins instance inside of a GitLab job, including plugins. This can help ease the process
+We are building a [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/) which
+you can use to run a complete Jenkins instance inside of a GitLab job, including plugins. This can help ease the process
 of transition, by letting you delay the migration of less urgent pipelines for a period of time.
 
 If you are interested in helping GitLab test the wrapper, join our [public testing issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215675) for instructions and to provide your feedback.
@@ -103,8 +103,8 @@ There are some high level differences between the products worth mentioning:
 - One important difference is that jobs run independently of each other and have a
   fresh environment in each job. Passing artifacts between jobs is controlled using the
   [`artifacts`](../yaml/README.md#artifacts) and [`dependencies`](../yaml/README.md#dependencies)
-  keywords. When finished, the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265)
-  feature will allow you to more easily persist a common workspace between serial jobs.
+  keywords. When finished, use the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265)
+  feature to more easily persist a common workspace between serial jobs.
 - The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but
   is in the YAML format (see [complete reference](../yaml/README.md)) instead of a Groovy DSL. It's most
   analogous to the declarative Jenkinsfile format.
@@ -114,7 +114,7 @@ There are some high level differences between the products worth mentioning:
 - GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using
   container images to set up your build environment. For example, set up one pipeline that builds your build environment
   itself and publish that to the container registry. Then, have your pipelines use this instead of each building their
-  own environment, which will be slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md).
+  own environment, which is slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md).
 - A central utilities repository can be a great place to put assorted scheduled jobs
   or other manual jobs that function like utilities. Jenkins installations tend to
   have a few of these.
@@ -129,12 +129,12 @@ agents you were using.
 There are some important differences in the way runners work in comparison to agents:
 
 - Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/README.md#types-of-runners).
-  They will self-select jobs from the scopes you've defined automatically.
+  They self-select jobs from the scopes you've defined automatically.
 - You can also [use tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and
   associate runners with specific jobs. For example, you can use a tag for jobs that
   require dedicated, more powerful, or specific hardware.
-- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html)
-  which will let you configure them to be provisioned as needed, and scaled down when not.
+- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html).
+  Use autoscaling to provision runners only when needed, and scale down when not needed.
   This is similar to ephemeral agents in Jenkins.
 
 If you are using `gitlab.com`, you can take advantage of our [shared runner fleet](../../user/gitlab_com/index.md#shared-runners)
@@ -227,15 +227,15 @@ and is meant to be a mapping of concepts there to concepts in GitLab.
 
 #### `agent`
 
-The agent section is used to define how a pipeline will be executed. For GitLab, we use [runners](../runners/README.md)
+The agent section is used to define how a pipeline executes. For GitLab, we use [runners](../runners/README.md)
 to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage
-of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users.) The link above will bring you to the documentation which will describe how to get
-up and running quickly. We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs
+of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users).
+We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs
 to different runners (execution agents).
 
 The `agent` section also allows you to define which Docker images should be used for execution, for which we use
 the [`image`](../yaml/README.md#image) keyword. The `image` can be set on a single job or at the top level, in which
-case it will apply to all jobs in the pipeline:
+case it applies to all jobs in the pipeline:
 
 ```yaml
 my_job:
@@ -246,7 +246,7 @@ my_job:
 
 The `post` section defines the actions that should be performed at the end of the pipeline. GitLab also supports
 this through the use of stages. You can define your stages as follows, and any jobs assigned to the `before_pipeline`
-or `after_pipeline` stages will run as expected. You can call these stages anything you like:
+or `after_pipeline` stages run as expected. You can call these stages anything you like:
 
 ```yaml
 stages:
diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md
index 5837bf6cf6b..c06eea20f6c 100644
--- a/doc/ci/multi_project_pipelines.md
+++ b/doc/ci/multi_project_pipelines.md
@@ -46,7 +46,7 @@ When you configure GitLab CI/CD for your project, you can visualize the stages o
 ![Multi-project pipeline graph](img/multi_project_pipeline_graph.png)
 
 In the Merge Request Widget, multi-project pipeline mini-graphs are displayed,
-and when hovering or tapping (on touchscreen devices) they will expand and be shown adjacent to each other.
+and when hovering or tapping (on touchscreen devices) they expand and are shown adjacent to each other.
 
 ![Multi-project mini graph](img/multi_pipeline_mini_graph.gif)
 
@@ -97,16 +97,16 @@ staging:
   trigger: my/deployment
 ```
 
-In the example above, as soon as `rspec` job succeeds in the `test` stage,
-the `staging` bridge job is going to be started. The initial status of this
-job will be `pending`. GitLab will create a downstream pipeline in the
-`my/deployment` project and, as soon as the pipeline gets created, the
-`staging` job will succeed. `my/deployment` is a full path to that project.
+In the example above, as soon as the `rspec` job succeeds in the `test` stage,
+the `staging` bridge job is started. The initial status of this
+job is `pending`. GitLab then creates a downstream pipeline in the
+`my/deployment` project and, as soon as the pipeline is created, the
+`staging` job succeeds. `my/deployment` is a full path to that project.
 
 The user that created the upstream pipeline needs to have access rights to the
-downstream project (`my/deployment` in this case). If a downstream project can
-not be found, or a user does not have access rights to create pipeline there,
-the `staging` job is going to be marked as _failed_.
+downstream project (`my/deployment` in this case). If a downstream project is
+not found, or a user does not have access rights to create a pipeline there,
+the `staging` job is marked as _failed_.
 
 When using:
 
@@ -117,21 +117,18 @@ When using:
 - [`only/except`](yaml/README.md#onlyexcept-basic) to control job behavior, use the
   `pipelines` keyword.
 
-CAUTION: **Caution:**
-In the example, `staging` will be marked as succeeded as soon as a downstream pipeline
+In the example, `staging` is marked as successful as soon as a downstream pipeline
 gets created. If you want to display the downstream pipeline's status instead, see
 [Mirroring status from triggered pipeline](#mirroring-status-from-triggered-pipeline).
 
 NOTE: **Note:**
-Bridge jobs do not support every configuration entry that a user can use
-in the case of regular jobs. Bridge jobs will not be picked by a runner,
-so there is no point in adding support for `script`, for example. If a user
-tries to use unsupported configuration syntax, YAML validation will fail upon
-pipeline creation.
+Bridge jobs [do not support every configuration keyword](#limitations) that can be used
+with other jobs. If a user tries to use unsupported configuration keywords, YAML
+validation fails on pipeline creation.
 
 ### Specifying a downstream pipeline branch
 
-It is possible to specify a branch name that a downstream pipeline will use:
+It is possible to specify a branch name that a downstream pipeline uses:
 
 ```yaml
 rspec:
@@ -152,7 +149,7 @@ Use:
   [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/10126), variable expansion is
   supported.
 
-GitLab will use a commit that is currently on the HEAD of the branch when
+GitLab uses a commit that is on the head of the branch when
 creating a downstream pipeline.
 
 NOTE: **Note:**
@@ -181,10 +178,10 @@ staging:
   trigger: my/deployment
 ```
 
-The `ENVIRONMENT` variable will be passed to every job defined in a downstream
-pipeline. It will be available as an environment variable when GitLab Runner picks a job.
+The `ENVIRONMENT` variable is passed to every job defined in a downstream
+pipeline. It is available as an environment variable when GitLab Runner picks a job.
 
-In the following configuration, the `MY_VARIABLE` variable will be passed to the downstream pipeline
+In the following configuration, the `MY_VARIABLE` variable is passed to the downstream pipeline
 that is created when the `trigger-downstream` job is queued. This is because `trigger-downstream`
 job inherits variables declared in global variables blocks, and then we pass these variables to a downstream pipeline.
 
@@ -210,7 +207,7 @@ downstream-job:
 ```
 
 In this scenario, the `UPSTREAM_BRANCH` variable with a value related to the
-upstream pipeline will be passed to the `downstream-job` job, and will be available
+upstream pipeline is passed to the `downstream-job` job, and is available
 within the context of all downstream builds.
 
 Upstream pipelines take precedence over downstream ones. If there are two
@@ -289,9 +286,9 @@ upstream_bridge:
 
 ### Limitations
 
-Because bridge jobs are a little different to regular jobs, it is not
-possible to use exactly the same configuration syntax here, as one would
-normally do when defining a regular job that will be picked by a runner.
+Bridge jobs are a little different from regular jobs. It is not
+possible to use exactly the same configuration syntax as when defining regular jobs
+that are picked by a runner.
 
 Some features are not implemented yet. For example, support for environments.
 
@@ -318,7 +315,7 @@ tag in a different project:
 1. Click subscribe.
 
 Any pipelines that complete successfully for new tags in the subscribed project
-will now trigger a pipeline on the current project's default branch. The maximum
+now trigger a pipeline on the current project's default branch. The maximum
 number of upstream pipeline subscriptions is 2 by default, for both the upstream and
 downstream projects. This [application limit](../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) can be changed on self-managed instances by a GitLab administrator.
 
diff --git a/doc/ci/parent_child_pipelines.md b/doc/ci/parent_child_pipelines.md
index b177751d5da..f5a39a8b7c8 100644
--- a/doc/ci/parent_child_pipelines.md
+++ b/doc/ci/parent_child_pipelines.md
@@ -52,8 +52,8 @@ For an overview, see [Parent-Child Pipelines feature demo](https://youtu.be/n8Kp
 ## Examples
 
 The simplest case is [triggering a child pipeline](yaml/README.md#trigger) using a
-local YAML file to define the pipeline configuration. In this case, the parent pipeline will
-trigger the child pipeline, and continue without waiting:
+local YAML file to define the pipeline configuration. In this case, the parent pipeline
+triggers the child pipeline, and continues without waiting:
 
 ```yaml
 microservice_a:
diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md
index 77614424b33..32636f5df51 100644
--- a/doc/ci/pipelines/pipeline_architectures.md
+++ b/doc/ci/pipelines/pipeline_architectures.md
@@ -22,8 +22,8 @@ any of the keywords used below, check out our [CI YAML reference](../yaml/README
 
 ## Basic Pipelines
 
-This is the simplest pipeline in GitLab. It will run everything in the build stage concurrently,
-and once all of those finish, it will run everything in the test stage the same way, and so on.
+This is the simplest pipeline in GitLab. It runs everything in the build stage concurrently,
+and once all of those finish, it runs everything in the test stage the same way, and so on.
 It's not the most efficient, and if you have lots of steps it can grow quite complex, but it's
 easier to maintain:
 
@@ -101,7 +101,7 @@ your jobs. When GitLab knows the relationships between your jobs, it can run eve
 as fast as possible, and even skips into subsequent stages when possible.
 
 In the example below, if `build_a` and `test_a` are much faster than `build_b` and
-`test_b`, GitLab will start `deploy_a` even if `build_b` is still running.
+`test_b`, GitLab starts `deploy_a` even if `build_b` is still running.
 
 ```mermaid
 graph LR
@@ -163,7 +163,7 @@ deploy_b:
 
 In the examples above, it's clear we've got two types of things that could be built independently.
 This is an ideal case for using [Child / Parent Pipelines](../parent_child_pipelines.md)) via
-the [`trigger` keyword](../yaml/README.md#trigger). It will separate out the configuration
+the [`trigger` keyword](../yaml/README.md#trigger). It separates out the configuration
 into multiple files, keeping things very simple. You can also combine this with:
 
 - The [`rules` keyword](../yaml/README.md#rules): For example, have the child pipelines triggered only
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md
index f3e60fae13a..851336b77ab 100644
--- a/doc/ci/quick_start/README.md
+++ b/doc/ci/quick_start/README.md
@@ -53,7 +53,7 @@ must [install GitLab Runner](https://docs.gitlab.com/runner/install/) and
 [register](https://docs.gitlab.com/runner/register/) at least one runner.
 
 If you are testing CI/CD, you can install GitLab Runner and register runners on your local machine.
-When your CI/CD jobs run, they will run on your local machine.
+When your CI/CD jobs run, they run on your local machine.
 
 ### Create a `.gitlab-ci.yml` file
 
diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md
index a329331df08..8f00db69e51 100644
--- a/doc/ci/ssh_keys/README.md
+++ b/doc/ci/ssh_keys/README.md
@@ -36,7 +36,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/)
    `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys)
    if you are accessing a private GitLab repository.
 
-The private key will not be displayed in the job log, unless you enable
+The private key is displayed in the job log, unless you enable
 [debug logging](../variables/README.md#debug-logging). You might also want to
 check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines).
 
@@ -46,7 +46,7 @@ When your CI/CD jobs run inside Docker containers (meaning the environment is
 contained) and you want to deploy your code in a private server, you need a way
 to access it. This is where an SSH key pair comes in handy.
 
-1. You will first need to create an SSH key pair. For more information, follow
+1. You first need to create an SSH key pair. For more information, follow
    the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair).
    **Do not** add a passphrase to the SSH key, or the `before_script` will
    prompt for it.
@@ -144,9 +144,9 @@ For accessing repositories on GitLab.com, you would use `git@gitlab.com`.
 ## Verifying the SSH host keys
 
 It is a good practice to check the private server's own public key to make sure
-you are not being targeted by a man-in-the-middle attack. In case anything
-suspicious happens, you will notice it since the job would fail (the SSH
-connection would fail if the public keys would not match).
+you are not being targeted by a man-in-the-middle attack. If anything
+suspicious happens, you notice it because the job fails (the SSH
+connection fails when the public keys don't match).
 
 To find out the host keys of your server, run the `ssh-keyscan` command from a
 trusted network (ideally, from the private server itself):
@@ -169,8 +169,8 @@ TIP: **Tip:**
 By using a variable instead of `ssh-keyscan` directly inside
 `.gitlab-ci.yml`, it has the benefit that you don't have to change `.gitlab-ci.yml`
 if the host domain name changes for some reason. Also, the values are predefined
-by you, meaning that if the host keys suddenly change, the CI/CD job will fail,
-and you'll know there's something wrong with the server or the network.
+by you, meaning that if the host keys suddenly change, the CI/CD job doesn't fail,
+so there's something wrong with the server or the network.
 
 Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the
 [content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor)
@@ -209,4 +209,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
 [shared runners](../runners/README.md).
 
 Want to hack on it? Simply fork it, commit and push your changes. Within a few
-moments the changes will be picked by a public runner and the job will begin.
+moments the changes is picked by a public runner and the job starts.
diff --git a/doc/ci/test_cases/img/test_case_list_v13_6.png b/doc/ci/test_cases/img/test_case_list_v13_6.png
new file mode 100644
index 00000000000..b5d89582558
--- /dev/null
+++ b/doc/ci/test_cases/img/test_case_list_v13_6.png
diff --git a/doc/ci/test_cases/img/test_case_show_v13_6.png b/doc/ci/test_cases/img/test_case_show_v13_6.png
new file mode 100644
index 00000000000..bbd7601cf30
--- /dev/null
+++ b/doc/ci/test_cases/img/test_case_show_v13_6.png
diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md
new file mode 100644
index 00000000000..5defbf632e2
--- /dev/null
+++ b/doc/ci/test_cases/index.md
@@ -0,0 +1,80 @@
+---
+stage: Plan
+group: Certify
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+description: Test cases in GitLab can help your teams create testing scenarios in their existing development platform.
+type: reference
+---
+
+# Test Cases **(ULTIMATE)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233479) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6.
+> - It's [deployed behind a feature flag](../../user/feature_flags.md), enabled by default.
+> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/241983) on GitLab 13.6.
+> - It's enabled on GitLab.com.
+> - It's recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-test-cases). **(ULTIMATE ONLY)**
+
+Test cases in GitLab can help your teams create testing scenarios in their existing development platform.
+
+This can help the Implementation and Testing teams collaborate, because they no longer have to
+use external test planning tools, which require additional overhead, context switching, and expense.
+
+## Create a test case
+
+To create a test case in a GitLab project:
+
+1. Navigate to **CI/CD > Test Cases**.
+1. Select the **New test case** button. You are taken to the new test case form. Here you can enter
+   the new case's title, [description](../../user/markdown.md), attach a file, and assign [labels](../../user/project/labels.md).
+1. Select the **Submit test case** button. You are taken to view the new test case.
+
+## View a test case
+
+You can view all test cases in the project in the Test Cases list. Filter the
+issue list with a search query, including labels or the test case's title.
+
+![Test case list page](img/test_case_list_v13_6.png)
+
+To view a test case:
+
+1. In a project, navigate to **CI/CD > Test Cases**.
+1. Select the title of the test case you want to view. You are taken to the test case page.
+
+![An example test case page](img/test_case_show_v13_6.png)
+
+## Archive a test case
+
+When you want to stop using a test case, you can archive it. You can [reopen an archived test case](#reopen-an-archived-test-case) later.
+
+To archive a test case, on the test case's page, select the **Archive test case** button.
+
+To view archived test cases:
+
+1. Navigate to **CI/CD > Test Cases**.
+1. Select **Archived**.
+
+## Reopen an archived test case
+
+If you decide to start using an archived test case again, you can reopen it.
+
+To reopen an archived test case, on the test case's page, select the **Reopen test case** button.
+
+### Enable or disable Test Cases **(ULTIMATE ONLY)**
+
+The GitLab Test Cases feature is under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can opt to disable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:quality_test_cases, Project.find_by_full_path('<project_path>'))
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:quality_test_cases, Project.find_by_full_path('<project_path>'))
+```
diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md
index 6fca482975c..9356e9f4614 100644
--- a/doc/ci/triggers/README.md
+++ b/doc/ci/triggers/README.md
@@ -268,5 +268,5 @@ This behavior can also be achieved through GitLab's UI with
 Old triggers, created before GitLab 9.0 are marked as legacy.
 
 Triggers with the legacy label do not have an associated user and only have
-access to the current project. They are considered deprecated and will be
+access to the current project. They are considered deprecated and might be
 removed with one of the future versions of GitLab.
diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md
index 71e2b5b2e44..efb89499c1c 100644
--- a/doc/ci/variables/deprecated_variables.md
+++ b/doc/ci/variables/deprecated_variables.md
@@ -17,7 +17,7 @@ To follow conventions of naming across GitLab, and to further move away from the
 release.
 
 Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are
-strongly advised to use the new variables as we will remove the old ones in
+strongly advised to use the new variables as we might remove the old ones in
 future GitLab releases.**
 
 | 8.x name              | 9.0+ name               |
diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md
index b914f3db572..4562fc75a55 100644
--- a/doc/ci/variables/where_variables_can_be_used.md
+++ b/doc/ci/variables/where_variables_can_be_used.md
@@ -57,8 +57,8 @@ There are three expansion mechanisms:
 ### GitLab internal variable expansion mechanism
 
 The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`.
-Each form is handled in the same way, no matter which OS/shell will finally handle the job,
-since the expansion is done in GitLab before any runner will get the job.
+Each form is handled in the same way, no matter which OS/shell handles the job,
+because the expansion is done in GitLab before any runner gets the job.
 
 ### GitLab Runner internal variable expansion mechanism
 
@@ -66,7 +66,7 @@ since the expansion is done in GitLab before any runner will get the job.
   variables from triggers, pipeline schedules, and manual pipelines.
 - Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`).
 
-The runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle
+The runner uses Go's `os.Expand()` method for variable expansion. It means that it handles
 only variables defined as `$variable` and `${variable}`. What's also important, is that
 the expansion is done only once, so nested variables may or may not work, depending on the
 ordering of variables definitions.
@@ -77,7 +77,7 @@ This is an expansion that takes place during the `script` execution.
 How it works depends on the used shell (`bash`, `sh`, `cmd`, PowerShell). For example, if the job's
 `script` contains a line `echo $MY_VARIABLE-${MY_VARIABLE_2}`, it should be properly handled
 by bash/sh (leaving empty strings or some values depending whether the variables were
-defined or not), but will not work with Windows' `cmd` or PowerShell, since these shells
+defined or not), but don't work with Windows' `cmd` or PowerShell, since these shells
 are using a different variables syntax.
 
 Supported:
@@ -87,10 +87,10 @@ Supported:
   `.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules).
 - The `script` may also use all variables defined in the lines before. So, for example, if you define
   a variable `export MY_VARIABLE="test"`:
-  - In `before_script`, it will work in the following lines of `before_script` and
+  - In `before_script`, it works in the following lines of `before_script` and
     all lines of the related `script`.
-  - In `script`, it will work in the following lines of `script`.
-  - In `after_script`, it will work in following lines of `after_script`.
+  - In `script`, it works in the following lines of `script`.
+  - In `after_script`, it works in following lines of `after_script`.
 
 In the case of `after_script` scripts, they can:
 
@@ -133,7 +133,7 @@ due to security reasons.
 Variables defined with an environment scope are supported. Given that
 there is a variable `$STAGING_SECRET` defined in a scope of
 `review/staging/*`, the following job that is using dynamic environments
-is going to be created, based on the matching variable expression:
+is created, based on the matching variable expression:
 
 ```yaml
 my-job:
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 1057a1389de..fa67916cc8f 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -13,15 +13,14 @@ This document lists the configuration options for your GitLab `.gitlab-ci.yml` f
 - For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md).
 - To view a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml).
 
-While you are authoring your `.gitlab-ci.yml` file, you can validate it
-by using the [CI Lint](../lint.md) tool.
-project namespace. For example, `https://gitlab.example.com/gitlab-org/project-123/-/ci/lint`.
+When you are editing your `.gitlab-ci.yml` file, you can validate it with the
+[CI Lint](../lint.md) tool.
 
 ## Job keywords
 
 A job is defined as a list of keywords that define the job's behavior.
 
-The following table lists available keywords for jobs:
+The keywords available for jobs are:
 
 | Keyword                                            | Description                                                                                                                                                                         |
 |:---------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -69,20 +68,20 @@ can't be used as job names**:
 - `cache`
 - `include`
 
-## Global keywords
-
-Some keywords must be defined at a global level, affecting all jobs in the pipeline.
+### Reserved keywords
 
-### Using reserved keywords
-
-If you get validation error when using specific values (for example, `true` or `false`), try to:
+If you get a validation error when using specific values (for example, `true` or `false`), try to:
 
 - Quote them.
 - Change them to a different form. For example, `/bin/true`.
 
+## Global keywords
+
+Some keywords are defined at a global level and affect all jobs in the pipeline.
+
 ### Global defaults
 
-Some keywords can be set globally as the default for all jobs using the
+Some keywords can be set globally as the default for all jobs with the
 `default:` keyword. Default keywords can then be overridden by job-specific
 configuration.
 
@@ -121,7 +120,7 @@ rspec 2.6:
 You can disable inheritance of globally defined defaults
 and variables with the `inherit:` keyword.
 
-To enable or disable the inheritance of all `variables:` or `default:` keywords, use the following format:
+To enable or disable the inheritance of all `default:` or `variables:` keywords, use:
 
 - `default: true` or `default: false`
 - `variables: true` or `variables: false`
@@ -201,14 +200,13 @@ karma:
 `stages` is used to define stages that contain jobs and is defined
 globally for the pipeline.
 
-The specification of `stages` allows for having flexible multi stage pipelines.
-The ordering of elements in `stages` defines the ordering of jobs' execution:
+The order of the `stages` items defines the execution order for jobs:
 
-1. Jobs of the same stage are run in parallel.
-1. Jobs of the next stage are run after the jobs from the previous stage
+1. Jobs in the same stage are run in parallel.
+1. Jobs in the next stage are run after the jobs from the previous stage
    complete successfully.
 
-Let's consider the following example, which defines 3 stages:
+For example:
 
 ```yaml
 stages:
@@ -341,17 +339,17 @@ include:
 > - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4.
 
-Using the `include` keyword allows the inclusion of external YAML files. This helps
-to break down the CI/CD configuration into multiple files and increases readability for long configuration files.
+Use the `include` keyword to include external YAML files in your CI/CD configuration. This
+breaks down the CI/CD configuration into multiple files and increases readability for long configuration files.
 It's also possible to have template files stored in a central repository and projects include their
 configuration files. This helps avoid duplicated configuration, for example, global default variables for all projects.
 
 `include` requires the external YAML file to have the extensions `.yml` or `.yaml`,
 otherwise the external file is not included.
 
-Using [YAML anchors](#anchors) across different YAML files sourced by `include` is not
-supported. You must only refer to anchors in the same file. Instead
-of using YAML anchors, you can use the [`extends` keyword](#extends).
+You can't use [YAML anchors](#anchors) across different YAML files sourced by `include`.
+You can only refer to anchors in the same file. Instead of YAML anchors, you can
+use the [`extends` keyword](#extends).
 
 `include` supports the following inclusion methods:
 
@@ -381,13 +379,13 @@ definitions. Local definitions in `.gitlab-ci.yml` override included definitions
 #### `include:local`
 
 `include:local` includes a file from the same repository as `.gitlab-ci.yml`.
-It's referenced using full paths relative to the root directory (`/`).
+It's referenced with full paths relative to the root directory (`/`).
 
 You can only use files that are tracked by Git on the same branch
-your configuration file is on. In other words, when using a `include:local`, make
+your configuration file is on. If you `include:local`, make
 sure that both `.gitlab-ci.yml` and the local file are on the same branch.
 
-Including local files through Git submodules paths is not supported.
+You can't include local files through Git submodules paths.
 
 All [nested includes](#nested-includes) are executed in the scope of the same project,
 so it's possible to use local, project, remote, or template includes.
@@ -412,7 +410,7 @@ include: '.gitlab-ci-production.yml'
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7.
 
 To include files from another private project under the same GitLab instance,
-use `include:file`. This file is referenced using full paths relative to the
+use `include:file`. This file is referenced with full paths relative to the
 root directory (`/`). For example:
 
 ```yaml
diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md
index d7945617dc9..ab5d61cdfc8 100644
--- a/doc/ci/yaml/includes.md
+++ b/doc/ci/yaml/includes.md
@@ -67,7 +67,7 @@ include:
 
 ## Re-using a `before_script` template
 
-In the following example, the content of `.before-script-template.yml` will be
+In the following example, the content of `.before-script-template.yml` is
 automatically fetched and evaluated along with the content of `.gitlab-ci.yml`.
 
 Content of `https://gitlab.com/awesome-project/raw/master/.before-script-template.yml`: