Add latest changes from gitlab-org/gitlab@master

4 files changed, 98 insertions, 69 deletions

diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml
new file mode 100644
index 00000000000..fe690d708ed
--- /dev/null
+++ b/doc/.vale/gitlab/SubstitutionWarning.yml
@@ -0,0 +1,16 @@
+---
+# Warns against using common shorthand for terms.
+# For substitutions flagged as errors, see Substitutions.yml
+#
+# For a list of all options, see https://errata-ai.github.io/vale/styles/
+extends: substitution
+message: 'If possible, use "%s" instead of "%s".'
+link: https://about.gitlab.com/handbook/communication/#top-misused-terms
+level: warning
+ignorecase: true
+swap:
+  admin: administrator
+  config: configuration
+  distro: distribution
+  info: information
+  repo: repository
diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml
index 0a96fe615e8..821134ab016 100644
--- a/doc/.vale/gitlab/Substitutions.yml
+++ b/doc/.vale/gitlab/Substitutions.yml
@@ -1,5 +1,6 @@
 ---
 # Checks for use of some of the top misused terms at GitLab.
+# For substitutions only flagged as warnings, see SubstitutionWarning.yml
 #
 # For a list of all options, see https://errata-ai.github.io/vale/styles/
 extends: substitution
diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index 38423a230ab..f9cb79f9db2 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -3,14 +3,15 @@
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/37115) in GitLab 10.0.
 > - Generally available on GitLab 11.0.
 
-Auto DevOps provides pre-defined CI/CD configuration which allows you to automatically detect, build, test,
-deploy, and monitor your applications. Leveraging CI/CD best practices and tools, Auto DevOps aims
-to simplify the setup and execution of a mature & modern software development lifecycle.
+Auto DevOps provides pre-defined CI/CD configuration allowing you to automatically
+detect, build, test, deploy, and monitor your applications. Leveraging CI/CD
+best practices and tools, Auto DevOps aims to simplify the setup and execution
+of a mature and modern software development lifecycle.
 
 ## Overview
 
 You can spend a lot of effort to set up the workflow and processes required to
-build, deploy. and monitor your project. It gets worse when your company has
+build, deploy, and monitor your project. It gets worse when your company has
 hundreds, if not thousands, of projects to maintain. With new projects
 constantly starting up, the entire software development process becomes
 impossibly complex to manage.
@@ -28,14 +29,14 @@ For an introduction to Auto DevOps, watch [AutoDevOps in GitLab 11.0](https://yo
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41729) in GitLab 11.3.
 
-Auto DevOps is enabled by default for all projects and will attempt to run on all pipelines
-in each project. This default can be enabled or disabled by an instance administrator in the
+Auto DevOps is enabled by default for all projects and attempts to run on all pipelines
+in each project. An instance administrator can enable or disable this default in the
 [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops-core-only).
-It will be automatically disabled in individual projects on their first pipeline failure,
+Auto DevOps automatically disables in individual projects on their first pipeline failure,
 if it has not been explicitly enabled for the project.
 
 Since [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/issues/26655), Auto DevOps
-will run on pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build)
+runs on pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build)
 exists.
 
 If a [CI/CD configuration file](../../ci/yaml/README.md) is present in the project,
@@ -44,17 +45,17 @@ it will continue to be used, whether or not Auto DevOps is enabled.
 ## Quick start
 
 If you're using GitLab.com, see the [quick start guide](quick_start_guide.md)
-for how to use Auto DevOps with GitLab.com and a Kubernetes cluster on Google Kubernetes
+for setting up Auto DevOps with GitLab.com and a Kubernetes cluster on Google Kubernetes
 Engine (GKE).
 
-If you're using a self-managed instance of GitLab, you will need to configure the
+If you use a self-managed instance of GitLab, you must configure the
 [Google OAuth2 OmniAuth Provider](../../integration/google.md) before
-you can configure a cluster on GKE. Once this is set up, you can follow the steps on the
-[quick start guide](quick_start_guide.md) to get started.
+configuring a cluster on GKE. After configuring the provider, you can follow
+the steps in the [quick start guide](quick_start_guide.md) to get started.
 
 ## Comparison to application platforms and PaaS
 
-Auto DevOps provides functionality that's often included in an application
+Auto DevOps provides features often included in an application
 platform or a Platform as a Service (PaaS). It takes inspiration from the
 innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it
 in multiple ways:
@@ -67,7 +68,7 @@ in multiple ways:
 - Auto DevOps has more features including security testing, performance testing,
   and code quality testing.
 - Auto DevOps offers an incremental graduation path. If you need advanced customizations,
-  you can start modifying the templates without having to start over on a
+  you can start modifying the templates without starting over on a
   completely different platform. Review the [customizing](customize.md) documentation for more information.
 
 ## Features
@@ -88,7 +89,7 @@ project in a simple and automatic way:
 1. [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing-premium) **(PREMIUM)**
 1. [Auto Monitoring](stages.md#auto-monitoring)
 
-As Auto DevOps relies on many different components, it's good to have a basic
+As Auto DevOps relies on many different components, you should have a basic
 knowledge of the following:
 
 - [Kubernetes](https://kubernetes.io/docs/home/)
@@ -109,51 +110,55 @@ Auto DevOps.
 
 ## Requirements
 
-To make full use of Auto DevOps, you will need:
+To make full use of Auto DevOps, you need:
 
-- **Kubernetes** (for Auto Review Apps, Auto Deploy, and Auto Monitoring)
+- **Kubernetes** (for [Auto Review Apps](stages.md#auto-review-apps),
+  [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring))
 
-  To enable deployments, you will need:
+  To enable deployments, you need:
 
-  1. A [Kubernetes 1.12+ cluster](../../user/project/clusters/index.md) for the project. The easiest
-     way is to create a [new cluster using the GitLab UI](../../user/project/clusters/add_remove_clusters.md#create-new-cluster).
-     For Kubernetes 1.16+ clusters, there is some additional configuration for [Auto Deploy for Kubernetes 1.16+](stages.md#kubernetes-116).
+  1. A [Kubernetes 1.12+ cluster](../../user/project/clusters/index.md) for your
+     project. The easiest way is to create a
+     [new cluster using the GitLab UI](../../user/project/clusters/add_remove_clusters.md#create-new-cluster).
+     For Kubernetes 1.16+ clusters, you must perform additional configuration for
+     [Auto Deploy for Kubernetes 1.16+](stages.md#kubernetes-116).
   1. NGINX Ingress. You can deploy it to your Kubernetes cluster by installing
      the [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress),
-     once you've configured GitLab's Kubernetes integration in the previous step.
+     after configuring GitLab's Kubernetes integration in the previous step.
 
      Alternatively, you can use the
      [`nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress)
      Helm chart to install Ingress manually.
 
      NOTE: **Note:**
-     If you're using your own Ingress instead of the one provided by GitLab's managed
+     If you use your own Ingress instead of the one provided by GitLab's managed
      apps, ensure you're running at least version 0.9.0 of NGINX Ingress and
      [enable Prometheus metrics](https://github.com/helm/charts/tree/master/stable/nginx-ingress#prometheus-metrics)
-     in order for the response metrics to appear. You will also have to
+     for the response metrics to appear. You must also
      [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)
      the NGINX Ingress deployment to be scraped by Prometheus using
      `prometheus.io/scrape: "true"` and `prometheus.io/port: "10254"`.
 
-- **Base domain** (for Auto Review Apps, Auto Deploy, and Auto Monitoring)
+- **Base domain** (for [Auto Review Apps](stages.md#auto-review-apps),
+  [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring))
 
-  You will need a domain configured with wildcard DNS which is going to be used
-  by all of your Auto DevOps applications. If you're using the
+  You need a domain configured with wildcard DNS, which all of your Auto DevOps
+  applications will use. If you're using the
   [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress),
-  the URL endpoint will be automatically configured for you.
+  the URL endpoint is automatically configured for you.
 
-  You will then need to [specify the Auto DevOps base domain](#auto-devops-base-domain).
+  You must also [specify the Auto DevOps base domain](#auto-devops-base-domain).
 
 - **GitLab Runner** (for all stages)
 
-  Your Runner needs to be configured to be able to run Docker. Generally this
-  means using either the [Docker](https://docs.gitlab.com/runner/executors/docker.html)
+  Your Runner must be configured to run Docker, usually with either the
+  [Docker](https://docs.gitlab.com/runner/executors/docker.html)
   or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executors, with
   [privileged mode enabled](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
   The Runners don't need to be installed in the Kubernetes cluster, but the
-  Kubernetes executor is easy to use and is automatically autoscaling.
-  Docker-based Runners can be configured to autoscale as well, using [Docker
-  Machine](https://docs.gitlab.com/runner/install/autoscaling.html).
+  Kubernetes executor is easy to use and automatically autoscales.
+  You can configure Docker-based Runners to autoscale as well, using
+  [Docker Machine](https://docs.gitlab.com/runner/install/autoscaling.html).
 
   If you've configured GitLab's Kubernetes integration in the first step, you
   can deploy it to your cluster by installing the
@@ -164,46 +169,51 @@ To make full use of Auto DevOps, you will need:
   that are assigned to specific projects (the default if you've installed the
   GitLab Runner managed application).
 
-- **Prometheus** (for Auto Monitoring)
+- **Prometheus** (for [Auto Monitoring](stages.md#auto-monitoring))
 
-  To enable Auto Monitoring, you will need Prometheus installed somewhere
-  (inside or outside your cluster) and configured to scrape your Kubernetes cluster.
+  To enable Auto Monitoring, you need Prometheus installed either inside or
+  outside your cluster, and configured to scrape your Kubernetes cluster.
   If you've configured GitLab's Kubernetes integration, you can deploy it to
   your cluster by installing the
   [GitLab-managed app for Prometheus](../../user/clusters/applications.md#prometheus).
 
   The [Prometheus service](../../user/project/integrations/prometheus.md)
-  integration needs to be enabled for the project (or enabled as a
+  integration must be enabled for the project, or enabled as a
   [default service template](../../user/project/integrations/services_templates.md)
-  for the entire GitLab installation).
+  for the entire GitLab installation.
 
-  To get response metrics (in addition to system metrics), you need to
+  To get response metrics (in addition to system metrics), you must
   [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-nginx-ingress-monitoring).
 
 - **cert-manager** (optional, for TLS/HTTPS)
 
-  To enable HTTPS endpoints for your application, you need to install cert-manager,
-  a native Kubernetes certificate management controller that helps with issuing certificates.
-  Installing cert-manager on your cluster will issue a certificate by
-  [Let’s Encrypt](https://letsencrypt.org/) and ensure that certificates are valid and up-to-date.
-  If you've configured GitLab's Kubernetes integration, you can deploy it to
-  your cluster by installing the
+  To enable HTTPS endpoints for your application, you must install cert-manager,
+  a native Kubernetes certificate management controller that helps with issuing
+  certificates. Installing cert-manager on your cluster issues a
+  [Let’s Encrypt](https://letsencrypt.org/) certificate and ensures the
+  certificates are valid and up-to-date. If you've configured GitLab's Kubernetes
+  integration, you can deploy it to your cluster by installing the
   [GitLab-managed app for cert-manager](../../user/clusters/applications.md#cert-manager).
 
-If you don't have Kubernetes or Prometheus installed, then Auto Review Apps,
-Auto Deploy, and Auto Monitoring will be silently skipped.
+If you don't have Kubernetes or Prometheus installed, then
+[Auto Review Apps](stages.md#auto-review-apps),
+[Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)
+are skipped.
 
-One all requirements are met, you can go ahead and [enable Auto DevOps](#enablingdisabling-auto-devops).
+After all requirements are met, you can [enable Auto DevOps](#enablingdisabling-auto-devops).
 
 ## Auto DevOps base domain
 
-The Auto DevOps base domain is required if you want to make use of
+The Auto DevOps base domain is required to use
 [Auto Review Apps](stages.md#auto-review-apps), [Auto Deploy](stages.md#auto-deploy), and
-[Auto Monitoring](stages.md#auto-monitoring). It can be defined in any of the following
-places:
-
-- either under the cluster's settings, whether for [projects](../../user/project/clusters/index.md#base-domain) or [groups](../../user/group/clusters/index.md#base-domain)
-- or in instance-wide settings in the **Admin Area > Settings** under the "Continuous Integration and Delivery" section
+[Auto Monitoring](stages.md#auto-monitoring). You can define the base domain in
+any of the following places:
+
+- either under the cluster's settings, whether for
+  [projects](../../user/project/clusters/index.md#base-domain) or
+  [groups](../../user/group/clusters/index.md#base-domain)
+- or in instance-wide settings in **{admin}** **Admin Area > Settings** under the
+  **Continuous Integration and Delivery** section
 - or at the project level as a variable: `KUBE_INGRESS_BASE_DOMAIN`
 - or at the group level as a variable: `KUBE_INGRESS_BASE_DOMAIN`.
 
@@ -211,9 +221,9 @@ The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of pr
 as other environment [variables](../../ci/variables/README.md#priority-of-environment-variables).
 
 TIP: **Tip:**
-If you're using the [GitLab managed app for Ingress](../../user/clusters/applications.md#ingress),
-the URL endpoint should be automatically configured for you.
-Use its value for the `KUBE_INGRESS_BASE_DOMAIN` variable.
+If you use the [GitLab managed app for Ingress](../../user/clusters/applications.md#ingress),
+the URL endpoint should be automatically configured for you. All you must do
+is use its value for the `KUBE_INGRESS_BASE_DOMAIN` variable.
 
 NOTE: **Note:**
 `AUTO_DEVOPS_DOMAIN` was [deprecated in GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-foss/issues/52363)
@@ -251,8 +261,7 @@ instance level.
 
 ### At the project level
 
-If enabling, confirm your project does not have a `.gitlab-ci.yml`. If one
-exists, remove it.
+If enabling, check that your project does not have a `.gitlab-ci.yml`, or if one exists, remove it.
 
 1. Go to your project's **{settings}** **Settings > CI/CD > Auto DevOps**.
 1. Select the **Default to Auto DevOps pipeline** checkbox to enable it.
@@ -329,7 +338,8 @@ When using Auto DevOps, you can deploy different environments to
 different Kubernetes clusters, due to the 1:1 connection
 [existing between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters-premium).
 
-The [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) currently defines 3 environment names:
+The [template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml)
+used by Auto DevOps currently defines 3 environment names:
 
 - `review/` (every environment starting with `review/`)
 - `staging`
@@ -358,23 +368,24 @@ To add a different cluster for each environment:
 
 1. After creating the clusters, navigate to each cluster and install Helm Tiller
    and Ingress. Wait for the Ingress IP address to be assigned.
-1. Make sure your [DNS is configured](#auto-devops-base-domain) with the
+1. Make sure you've [configured your DNS](#auto-devops-base-domain) with the
    specified Auto DevOps domains.
 1. Navigate to each cluster's page, through **{cloud-gear}** **Operations > Kubernetes**,
    and add the domain based on its Ingress IP address.
 
 After completing configuration, you can test your setup by creating a merge request
-and verifying your app is deployed as a review app in the Kubernetes
+and verifying your application is deployed as a Review App in the Kubernetes
 cluster with the `review/*` environment scope. Similarly, you can check the
 other environments.
 
 ## Currently supported languages
 
-Note that not all buildpacks support Auto Test yet, as it's a relatively new enhancement.
-All of Heroku's [officially supported languages](https://devcenter.heroku.com/articles/heroku-ci#currently-supported-languages)
-support Auto Test. While some third-party buildpacks, such as Go, Node, Java, PHP,
-Python, Ruby, Gradle, Scala, and Elixir all support Auto Test, the
-multi-buildpack notably does not.
+Note that not all buildpacks support Auto Test yet, as it's a relatively new
+enhancement. All of Heroku's [officially supported
+languages](https://devcenter.heroku.com/articles/heroku-ci#supported-languages)
+support buildpacks, and some third-party buildpacks as well (such as Go, Node, Java, PHP,
+Python, Ruby, Gradle, Scala, and Elixir) all support Auto Test, but notably the
+multi-buildpack does not.
 
 As of GitLab 10.0, the supported buildpacks are:
 
diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md
index 311e3ecc959..44e2d210910 100644
--- a/doc/user/project/deploy_tokens/index.md
+++ b/doc/user/project/deploy_tokens/index.md
@@ -3,6 +3,7 @@
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) in GitLab 10.7.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/199370) from **Settings > Repository** in GitLab 12.9.
 > - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10.
+> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1.
 
 Deploy tokens allow you to download (`git clone`) or push and pull the container registry images of a project without having a user and a password.
 
@@ -16,7 +17,7 @@ You can create as many deploy tokens as you like from the settings of your proje
 
 1. Log in to your GitLab account.
 1. Go to the project (or group) you want to create Deploy Tokens for.
-1. Go to **{settings}** **Settings** > **CI / CD**.
+1. Go to **{settings}** **Settings** > **Repository**.
 1. Click on "Expand" on **Deploy Tokens** section.
 1. Choose a name, expiry date (optional), and username (optional) for the token.
 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token).