Add latest changes from gitlab-org/gitlab@master

7 files changed, 81 insertions, 134 deletions

diff --git a/doc/ci/environments/img/deployments_list.png b/doc/ci/environments/img/deployments_list.png
index dd9dfbc60a7..95afc092d86 100644
--- a/doc/ci/environments/img/deployments_list.png
+++ b/doc/ci/environments/img/deployments_list.png
diff --git a/doc/ci/environments/img/environment_auto_stop_v13_10.png b/doc/ci/environments/img/environment_auto_stop_v13_10.png
new file mode 100644
index 00000000000..1525f670ff2
--- /dev/null
+++ b/doc/ci/environments/img/environment_auto_stop_v13_10.png
diff --git a/doc/ci/environments/img/environments_dynamic_groups_v13_10.png b/doc/ci/environments/img/environments_dynamic_groups_v13_10.png
new file mode 100644
index 00000000000..cf3f9f7c781
--- /dev/null
+++ b/doc/ci/environments/img/environments_dynamic_groups_v13_10.png
diff --git a/doc/ci/environments/img/environments_list.png b/doc/ci/environments/img/environments_list.png
index e627ec9c3db..6ddfd858ab6 100644
--- a/doc/ci/environments/img/environments_list.png
+++ b/doc/ci/environments/img/environments_list.png
diff --git a/doc/ci/environments/img/environments_terminal_button_on_index_v13_10.png b/doc/ci/environments/img/environments_terminal_button_on_index_v13_10.png
new file mode 100644
index 00000000000..13c8d1cd523
--- /dev/null
+++ b/doc/ci/environments/img/environments_terminal_button_on_index_v13_10.png
diff --git a/doc/ci/environments/img/environments_terminal_button_on_show_v13_10.png b/doc/ci/environments/img/environments_terminal_button_on_show_v13_10.png
new file mode 100644
index 00000000000..fcc3e2b6631
--- /dev/null
+++ b/doc/ci/environments/img/environments_terminal_button_on_show_v13_10.png
diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md
index be3007b8234..1aa8d6a3618 100644
--- a/doc/ci/environments/index.md
+++ b/doc/ci/environments/index.md
@@ -18,7 +18,7 @@ a deployment is created.
 GitLab:
 
 - Provides a full history of deployments to each environment.
-- Tracks your deployments, so you always know what is currently deployed on your
+- Tracks your deployments, so you always know what is deployed on your
   servers.
 
 If you have a deployment service like [Kubernetes](../../user/project/clusters/index.md)
@@ -116,8 +116,7 @@ In this example:
   use `$CI_ENVIRONMENT_SLUG` instead. The `$CI_ENVIRONMENT_SLUG` variable is guaranteed to be unique.
 
 You do not have to use the same prefix or only slashes (`/`) in the dynamic environment name.
-However, when you use this format, you can use the [grouping similar environments](#grouping-similar-environments)
-feature.
+However, when you use this format, you can [group similar environments](#group-similar-environments).
 
 NOTE:
 Some variables cannot be used as environment names or URLs.
@@ -184,8 +183,8 @@ deploy:
     - master
 ```
 
-When deploying to a Kubernetes cluster using the GitLab Kubernetes integration,
-information about the cluster and namespace is displayed above the job
+When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster,
+cluster and namespace information is displayed above the job
 trace on the deployment job page:
 
 ![Deployment cluster information](../img/environments_deployment_cluster_v12_8.png)
@@ -202,8 +201,8 @@ When you create an environment, you specify the name and URL.
 If you want to use the name or URL in another job, you can use:
 
 - `$CI_ENVIRONMENT_NAME`. The name defined in the `.gitlab-ci.yml` file.
-- `$CI_ENVIRONMENT_SLUG`. A "cleaned-up" version of the name, suitable for use in URLs,
-  DNS, etc. This variable is guaranteed to be unique.
+- `$CI_ENVIRONMENT_SLUG`. A "cleaned-up" version of the name, suitable for use in URL and DNS, for example.
+  This variable is guaranteed to be unique.
 - `$CI_ENVIRONMENT_URL`. The environment's URL, which was specified in the
   `.gitlab-ci.yml` file or automatically assigned.
 
@@ -220,12 +219,12 @@ If you change the name of an existing environment, the:
 In a job script, you can specify a static environment URL.
 However, there may be times when you want a dynamic URL. For example,
 if you deploy a Review App to an external hosting
-service that generates a random URL per deployment, like `https://94dd65b.amazonaws.com/qa-lambda-1234567`,
-you don't know the URL before the deployment script finishes.
+service that generates a random URL per deployment, like `https://94dd65b.amazonaws.com/qa-lambda-1234567`.
+In this case, you don't know the URL before the deployment script finishes.
 If you want to use the environment URL in GitLab, you would have to update it manually.
 
 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.
+variables. These variables include the URL that was dynamically-generated by the external service.
 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.
 
@@ -286,23 +285,6 @@ Note the following:
   for these jobs. This ensures that runners can fetch the repository even after a feature branch is
   deleted. For more information, see [Ref Specs for Runners](../pipelines/index.md#ref-specs-for-runners).
 
-## Deployment safety
-
-Deployment jobs can be more sensitive than other jobs in a pipeline,
-and might need to be treated with an extra care. There are multiple features
-in GitLab that help 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)
-- [Prevent deployments during deploy freeze windows](deployment_safety.md#prevent-deployments-during-deploy-freeze-windows)
-
-## Protected environments
-
-Environments can be "protected", restricting access to them.
-
-For more information, see [Protected environments](protected_environments.md).
-
 ## Working with environments
 
 Once environments are configured, GitLab provides many features for working with them,
@@ -331,8 +313,8 @@ To retry or rollback a deployment:
 
 ### Environment URL
 
-The [environment URL](../yaml/README.md#environmenturl) is exposed in a few
-places within GitLab:
+The [environment URL](../yaml/README.md#environmenturl) is displayed in a few
+places in GitLab:
 
 - In a merge request as a link:
   ![Environment URL in merge request](../img/environments_mr_review_app.png)
@@ -359,8 +341,8 @@ from source files to public pages in the environment set for Review Apps.
 
 When you stop an environment:
 
-- It moves from the list of **Available** environments to the list of **Stopped**
-  environments on the [**Environments** page](#view-environments-and-deployments).
+- On the **Environments** page, it moves from the list of **Available** environments
+  to the list of **Stopped** environments.
 - An [`on_stop` action](../yaml/README.md#environmenton_stop), if defined, is executed.
 
 Dynamic environments stop automatically when their associated branch is
@@ -368,10 +350,16 @@ deleted.
 
 #### Stop an environment when a branch is deleted
 
-Environments can be stopped automatically using special configuration.
+You can configure environments to stop when a branch is deleted.
 
-Consider the following example where the `deploy_review` job calls `stop_review`
-to clean up and stop the environment:
+The following example shows a `deploy_review` job that calls a `stop_review` job
+to clean up and stop the environment. The `stop_review` job must be in the same
+`stage` as the `deploy_review` job.
+
+Both jobs must have the same [`rules`](../yaml/README.md#onlyexcept-basic)
+or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. Otherwise,
+the `stop_review` job might not be included in all pipelines that include the
+`deploy_review` job, and you cannot trigger `action: stop` to stop the environment automatically.
 
 ```yaml
 deploy_review:
@@ -397,55 +385,30 @@ stop_review:
       when: manual
 ```
 
-If you can't use [Pipelines for merge requests](../merge_request_pipelines/index.md),
-setting the [`GIT_STRATEGY`](../runners/README.md#git-strategy) to `none` is necessary in the
-`stop_review` job so that the [runner](https://docs.gitlab.com/runner/) doesn't
+If you can't use [pipelines for merge requests](../merge_request_pipelines/index.md),
+set the [`GIT_STRATEGY`](../runners/README.md#git-strategy) to `none` in the
+`stop_review` job. Then the [runner](https://docs.gitlab.com/runner/) doesn't
 try to check out the code after the branch is deleted.
 
-When you have an environment that has a stop action defined (typically when
-the environment describes a Review App), GitLab automatically triggers a
-stop action when the associated branch is deleted. The `stop_review` job must
-be in the same `stage` as the `deploy_review` job in order for the environment
-to automatically stop.
-
-Additionally, both jobs should have matching [`rules`](../yaml/README.md#onlyexcept-basic)
-or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. In the example
-above, if the configuration isn't identical, the `stop_review` job might not be
-included in all pipelines that include the `deploy_review` job, and it isn't
-possible to trigger `action: stop` to stop the environment automatically.
-
-You can read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environmenton_stop).
+Read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environmenton_stop).
 
 #### Stop an environment after a certain time period
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
 
-You can set an expiry time for environments and stop them automatically after a certain period.
-
-For example, consider the use of this feature with Review App environments. When you set up Review
-Apps, sometimes they keep running for a long time because some merge requests are left open and
-forgotten. Such idle environments waste resources and should be terminated as soon as possible.
+You can set environments to stop automatically after a certain time period.
 
-To address this problem, you can specify an optional expiration date for Review App environments.
-When the expiry time is reached, GitLab automatically triggers a job to stop the environment,
-eliminating the need of manually doing so. In case an environment is updated, the expiration is
-renewed ensuring that only active merge requests keep running Review Apps.
+In your `.gitlab-ci.yml` file, specify the [`environment:auto_stop_in`](../yaml/README.md#environmentauto_stop_in)
+keyword. You can specify a human-friendly date as the value, such as `1 hour and 30 minutes` or `1 day`.
+After the time period passes, GitLab automatically triggers a job to stop the environment.
 
-To enable this feature, you must specify the [`environment:auto_stop_in`](../yaml/README.md#environmentauto_stop_in)
-keyword in `.gitlab-ci.yml`. 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 that due to resource limitation, a background worker for stopping environments only runs once
+Due to resource limitations, a background worker for stopping environments only runs once
 every hour. This means that environments aren't stopped at the exact timestamp specified, but are
 instead 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
-per merge request. The `review_app` job is triggered by every push and
-creates or updates an environment named `review/your-branch-name`.
-The environment keeps running until `stop_review_app` is executed:
+In the following example, each merge request creates a new Review App environment.
+Each push triggers the `review_app` job and an environment named `review/your-branch-name`
+is created or updated. The environment runs until `stop_review_app` is executed:
 
 ```yaml
 review_app:
@@ -467,48 +430,48 @@ stop_review_app:
       when: manual
 ```
 
-As long as a merge request is active and keeps getting new commits,
-the review app doesn't stop, so developers don't need to worry about
-re-initiating review app.
+As long as the merge request is active and keeps getting new commits,
+the Review App doesn't stop. Developers don't need to worry about
+re-initiating Review App.
 
-On the other hand, since `stop_review_app` is set to `auto_stop_in: 1 week`,
-if a merge request becomes inactive for more than a week,
+Because `stop_review_app` is set to `auto_stop_in: 1 week`,
+if a merge request is inactive for more than a week,
 GitLab automatically triggers the `stop_review_app` job to stop the environment.
 
-You can also check the expiration date of environments through the GitLab UI. To do so,
-go to **Operations > Environments > Environment**. You can see the auto-stop period
-at the left-top section and a pin-mark button at the right-top section. This pin-mark
-button can be used to prevent auto-stopping the environment. By clicking this button, the
-`auto_stop_in` setting is overwritten and the environment is active until it's stopped manually.
+#### View a deployment's scheduled stop time
 
-![Environment auto stop](../img/environment_auto_stop_v12_8.png)
+You can view a deployment's expiration date in the GitLab UI.
 
-#### Delete a stopped environment
+1. Go to the project's **Operations > Environments** page.
+1. Select the name of the deployment.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20620) in GitLab 12.10.
+In the top left, next to the environment name, the expiration date is displayed.
 
-You can delete [stopped environments](#stopping-an-environment) in one of two
-ways: through the GitLab UI or through the API.
+#### Override a deployment's scheduled stop time
 
-##### Delete environments through the UI
+You can manually override a deployment's expiration date.
 
-To view the list of **Stopped** environments, navigate to **Operations > Environments**
-and click the **Stopped** tab.
+1. Go to the project's **Operations > Environments** page.
+1. Select the deployment name.
+1. In the top right, select the thumbtack (**{thumbtack}**).
+
+![Environment auto stop](img/environment_auto_stop_v13_10.png)
 
-From there, you can click the **Delete** button directly, or you can click the
-environment name to see its details and **Delete** it from there.
+The `auto_stop_in` setting is overwritten and the environment remains active until it's stopped manually.
+
+#### Delete a stopped environment
 
-You can also delete environments by viewing the details for a
-stopped environment:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20620) in GitLab 12.10.
 
-  1. Go to the project's **Operations > Environments** page.
-  1. Click on the name of an environment within the **Stopped** environments list.
-  1. Click on the **Delete** button that appears at the top for all stopped environments.
-  1. Finally, confirm your chosen environment in the modal that appears to delete it.
+You can delete [stopped environments](#stopping-an-environment) in the GitLab UI or by using
+[the API](../../api/environments.md#delete-an-environment).
 
-##### Delete environments through the API
+To delete a stopped environment in the GitLab UI:
 
-Environments can also be deleted by using the [Environments API](../../api/environments.md#delete-an-environment).
+1. Go to the project's **Operations > Environments** page.
+1. Select the **Stopped** tab.
+1. Next to the environment you want to delete, select **Delete environment**.
+1. On the confirmation dialog box, select **Delete environment**.
 
 ### Prepare an environment
 
@@ -535,19 +498,19 @@ build:
     url: https://staging.example.com
 ```
 
-### Grouping similar environments
+### Group similar environments
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7015) in GitLab 8.14.
 
-As documented in [Create a dynamic environment](#create-a-dynamic-environment), you can
-prepend environment name with a word, followed by a `/`, and finally the branch
-name, which is automatically defined by the `CI_COMMIT_REF_NAME` predefined CI/CD variable.
+You can group environments into collapsible sections in the UI.
 
-In short, environments that are named like `type/foo` are all presented under the same
-group, named `type`.
+For example, if all of your environments start with the name `review`,
+then in the UI, the environments are grouped under that heading:
 
-If you name the environments `review/$CI_COMMIT_REF_NAME`
-where `$CI_COMMIT_REF_NAME` is the branch name:
+![Environment groups](img/environments_dynamic_groups_v13_10.png)
+
+The following example shows how to start your environment names with `review`.
+The `$CI_COMMIT_REF_NAME` variable is populated with the branch name at runtime:
 
 ```yaml
 deploy_review:
@@ -558,11 +521,6 @@ deploy_review:
     name: review/$CI_COMMIT_REF_NAME
 ```
 
-If you visit the **Environments** page and the branches
-exist, you should see something like:
-
-![Environment groups](../img/environments_dynamic_groups.png)
-
 ### Environment incident management
 
 You have successfully setup a Continuous Delivery/Deployment workflow in your project.
@@ -634,8 +592,6 @@ Once configured, GitLab attempts to retrieve [supported performance metrics](../
 for any environment that has had a successful deployment. If monitoring data was
 successfully retrieved, a **Monitoring** button appears for each environment.
 
-![Environment Detail with Metrics](../img/deployments_view.png)
-
 Clicking the **Monitoring** button displays a new page showing up to the last
 8 hours of performance data. It may take a minute or two for data to appear
 after initial deployment.
@@ -666,13 +622,13 @@ Note that container-based deployments often lack basic tools (like an editor), a
 be stopped or restarted at any time. If this happens, you lose all your
 changes. Treat this as a debugging tool, not a comprehensive online IDE.
 
-Once enabled, your environments gain a **Terminal** button:
+Once enabled, your environments display a **Terminal** button:
 
-![Terminal button on environment index](../img/environments_terminal_button_on_index.png)
+![Terminal button on environment index](img/environments_terminal_button_on_index_v13_10.png)
 
 You can also access the terminal button from the page for a specific environment:
 
-![Terminal button for an environment](../img/environments_terminal_button_on_show.png)
+![Terminal button for an environment](img/environments_terminal_button_on_show_v13_10.png)
 
 Wherever you find it, clicking the button takes you to a separate page to
 establish the terminal session:
@@ -749,24 +705,15 @@ such as [Review Apps](../review_apps/index.md) (`review/*`).
 Note that the most _specific_ spec takes precedence over the other wildcard matching. In this case,
 the `review/feature-1` spec takes precedence over `review/*` and `*` specs.
 
-### Environments Dashboard **(PREMIUM)**
-
-See [Environments Dashboard](../environments/environments_dashboard.md) for a summary of each
-environment's operational health.
-
-## Limitations
-
-In the `environment: name`, you are limited to only the [predefined CI/CD variables](../variables/predefined_variables.md).
-Re-using variables defined inside `script` as part of the environment name doesn't work.
-
-## Further reading
-
-Below are some links you may find interesting:
+## Related topics
 
-- [The `.gitlab-ci.yml` definition of environments](../yaml/README.md#environment)
-- [A blog post on Deployments & Environments](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/)
-- [Review Apps - Use dynamic environments to deploy your code for every branch](../review_apps/index.md)
-- [Deploy Boards for your applications running on Kubernetes](../../user/project/deploy_boards.md)
+- [Use GitLab CI to deploy to multiple environments (blog post)](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/)
+- [Review Apps](../review_apps/index.md): Use dynamic environments to deploy your code for every branch.
+- [Deploy Boards](../../user/project/deploy_boards.md): View the status of your applications running on Kubernetes.
+- [Protected environments](protected_environments.md): Determine who can deploy code to your environments.
+- [Environments Dashboard](../environments/environments_dashboard.md): View a summary of each
+  environment's operational health. **(PREMIUM)**
+- [Deployment safety](deployment_safety.md#restrict-write-access-to-a-critical-environment): Secure your deployments.
 
 <!-- ## Troubleshooting