Add latest changes from gitlab-org/gitlab@13-2-stable-ee

3 files changed, 55 insertions, 31 deletions

diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md
index 055baa78743..a4ff164a5ba 100644
--- a/doc/ci/environments/deployment_safety.md
+++ b/doc/ci/environments/deployment_safety.md
@@ -7,7 +7,7 @@ that help maintain deployment security and stability.
 You can:
 
 - [Restrict write-access to a critical environment](#restrict-write-access-to-a-critical-environment)
-- [Restrict deployments for a particular period](#restrict-deployments-for-a-particular-period)
+- [Prevent deployments during deploy freeze windows](#prevent-deployments-during-deploy-freeze-windows)
 
 If you are using a continuous deployment workflow and want to ensure that concurrent deployments to the same environment do not happen, you should enable the following options:
 
@@ -77,10 +77,10 @@ The improved pipeline flow **after** enabling Skip outdated deployment jobs:
 1. The `deploy` job in Pipeline-B finishes first, and deploys the newer code.
 1. The `deploy` job in Pipeline-A is automatically cancelled, so that it doesn't overwrite the deployment from the newer pipeline.
 
-## Restrict deployments for a particular period
+## Prevent deployments during deploy freeze windows
 
 If you want to prevent deployments for a particular period, for example during a planned
-vacation period when most employees are out, you can set up a [Deploy Freeze](../../user/project/releases/index.md#set-a-deploy-freeze).
+vacation period when most employees are out, you can set up a [Deploy Freeze](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze).
 During a deploy freeze period, no deployment can be executed. This is helpful to
 ensure that deployments do not happen unexpectedly.
 
diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md
index 84480b836f8..0273ab290a6 100644
--- a/doc/ci/environments/index.md
+++ b/doc/ci/environments/index.md
@@ -94,7 +94,7 @@ deploy_staging:
     name: staging
     url: https://staging.example.com
   only:
-  - master
+    - master
 ```
 
 We have defined three [stages](../yaml/README.md#stages):
@@ -124,7 +124,7 @@ The environment `name` and `url` is exposed in various places
 within GitLab. Each time a job that has an environment specified
 succeeds, a deployment is recorded, along with the Git SHA, and environment name.
 
-CAUTION: **Caution**:
+CAUTION: **Caution:**
 Some characters are not allowed in environment names. Use only letters,
 numbers, spaces, and `-`, `_`, `/`, `{`, `}`, or `.`. Also, it must not start nor end with `/`.
 
@@ -173,8 +173,8 @@ If you want to use the environment URL in GitLab, you would have to update it ma
 
 To address this problem, you can configure a deployment job to report back a set of
 variables, including the URL that was dynamically-generated by the external service.
-GitLab supports [dotenv](https://github.com/bkeepers/dotenv) file as the format,
-and expands the `environment:url` value with variables defined in the dotenv file.
+GitLab supports the [dotenv (`.env`)](https://github.com/bkeepers/dotenv) file format,
+and expands the `environment:url` value with variables defined in the `.env` file.
 
 To use this feature, specify the
 [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
@@ -213,14 +213,13 @@ stop_review:
 
 As soon as the `review` job finishes, GitLab updates the `review/your-branch-name`
 environment's URL.
-It parses the report artifact `deploy.env`, registers a list of variables as runtime-created,
+It parses the `deploy.env` report artifact, registers a list of variables as runtime-created,
 uses it for expanding `environment:url: $DYNAMIC_ENVIRONMENT_URL` and sets it to the environment URL.
 You can also specify a static part of the URL at `environment:url:`, such as
 `https://$DYNAMIC_ENVIRONMENT_URL`. If the value of `DYNAMIC_ENVIRONMENT_URL` is
-`123.awesome.com`, the final result will be `https://123.awesome.com`.
+`example.com`, the final result will be `https://example.com`.
 
-The assigned URL for the `review/your-branch-name` environment is visible in the UI.
-[See where the environment URL is displayed](#using-the-environment-url).
+The assigned URL for the `review/your-branch-name` environment is [visible in the UI](#using-the-environment-url).
 
 > **Notes:**
 >
@@ -260,7 +259,7 @@ deploy_staging:
     name: staging
     url: https://staging.example.com
   only:
-  - master
+    - master
 
 deploy_prod:
   stage: deploy
@@ -271,7 +270,7 @@ deploy_prod:
     url: https://example.com
   when: manual
   only:
-  - master
+    - master
 ```
 
 The `when: manual` action:
@@ -306,11 +305,6 @@ declaring their names dynamically in `.gitlab-ci.yml`.
 
 Dynamic environments are a fundamental part of [Review apps](../review_apps/index.md).
 
-### Configuring incremental rollouts
-
-Learn how to release production changes to only a portion of your Kubernetes pods with
-[incremental rollouts](../environments/incremental_rollouts.md).
-
 #### Allowed variables
 
 The `name` and `url` parameters for dynamic environments can use most available CI/CD variables,
@@ -408,7 +402,7 @@ deploy:
     kubernetes:
       namespace: production
   only:
-  - master
+    - master
 ```
 
 When deploying to a Kubernetes cluster using GitLab's Kubernetes integration,
@@ -423,6 +417,11 @@ that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed
 To follow progress on support for GitLab-managed clusters, see the
 [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054).
 
+#### Configuring incremental rollouts
+
+Learn how to release production changes to only a portion of your Kubernetes pods with
+[incremental rollouts](../environments/incremental_rollouts.md).
+
 ### Deployment safety
 
 Deployment jobs can be more sensitive than other jobs in a pipeline,
@@ -432,7 +431,7 @@ in GitLab that helps maintain deployment security and stability.
 - [Restrict write-access to a critical environment](deployment_safety.md#restrict-write-access-to-a-critical-environment)
 - [Limit the job-concurrency for deployment jobs](deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time)
 - [Skip outdated deployment jobs](deployment_safety.md#skip-outdated-deployment-jobs)
-- [Restrict deployments for a particular period](deployment_safety.md#restrict-deployments-for-a-particular-period)
+- [Prevent deployments during deploy freeze windows](deployment_safety.md#prevent-deployments-during-deploy-freeze-windows)
 
 ### Complete example
 
@@ -484,7 +483,7 @@ deploy_staging:
     name: staging
     url: https://staging.example.com
   only:
-  - master
+    - master
 
 deploy_prod:
   stage: deploy
@@ -495,7 +494,7 @@ deploy_prod:
     url: https://example.com
   when: manual
   only:
-  - master
+    - master
 ```
 
 A more realistic example would also include copying files to a location where a
@@ -740,6 +739,12 @@ To enable this feature, you need to specify the [`environment:auto_stop_in`](../
 You can specify a human-friendly date as the value, such as `1 hour and 30 minutes` or `1 day`.
 `auto_stop_in` uses the same format of [`artifacts:expire_in` docs](../yaml/README.md#artifactsexpire_in).
 
+NOTE: **Note:**
+Due to the resource limitation, a background worker for stopping environments only
+runs once every hour. This means environments will not be stopped at the exact
+timestamp as the specified period, but will be stopped when the hourly cron worker
+detects expired environments.
+
 ##### Auto-stop example
 
 In the following example, there is a basic review app setup that creates a new environment
@@ -779,15 +784,9 @@ and the environment will be active until it's stopped manually.
 
 ![Environment auto stop](../img/environment_auto_stop_v12_8.png)
 
-NOTE: **NOTE**
-Due to the resource limitation, a background worker for stopping environments only
-runs once every hour. This means environments will not be stopped at the exact
-timestamp as the specified period, but will be stopped when the hourly cron worker
-detects expired environments.
-
 #### Delete a stopped environment
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22629) in GitLab 12.9.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20620) in GitLab 12.10.
 
 You can delete [stopped environments](#stopping-an-environment) in one of two
 ways: through the GitLab UI or through the API.
@@ -812,6 +811,31 @@ stopped environment:
 
 Environments can also be deleted by using the [Environments API](../../api/environments.md#delete-an-environment).
 
+### Prepare an environment
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) in GitLab 13.2.
+
+By default, GitLab creates a [deployment](#viewing-deployment-history) every time a
+build with the specified environment runs. Newer deployments can also
+[cancel older ones](deployment_safety.md#skip-outdated-deployment-jobs).
+
+You may want to specify an environment keyword to
+[protect builds from unauthorized access](protected_environments.md), or to get
+access to [scoped variables](#scoping-environments-with-specs). In these cases,
+you can use the `action: prepare` keyword to ensure deployments won't be created,
+and no builds would be canceled:
+
+```yaml
+build:
+  stage: build
+  script:
+    - echo "Building the app"
+  environment:
+    name: staging
+    action: prepare
+    url: https://staging.example.com
+```
+
 ### Grouping similar environments
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7015) in GitLab 8.14.
@@ -868,7 +892,7 @@ versions of the app, all without leaving GitLab.
 
 #### Embedding metrics in GitLab Flavored Markdown
 
-Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab Flavored Markdown](../../user/project/integrations/prometheus.md#embedding-metric-charts-within-gitlab-flavored-markdown) for more details.
+Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab Flavored Markdown](../../operations/metrics/embed.md) for more details.
 
 ### Web terminals
 
diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md
index 3a44fcfb182..b6141ddc7ac 100644
--- a/doc/ci/environments/protected_environments.md
+++ b/doc/ci/environments/protected_environments.md
@@ -22,7 +22,7 @@ specific environments are "protected" to prevent unauthorized people from affect
 By default, a protected environment does one thing: it ensures that only people
 with the right privileges can deploy to it, thus keeping it safe.
 
-NOTE: **Note**:
+NOTE: **Note:**
 A GitLab admin is always allowed to use environments, even if they are protected.
 
 To protect, update, or unprotect an environment, you need to have at least