Edited down for style and CTRT

Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/300312/

doc/api/deployments.md

@@ -22,7 +22,7 @@ GET /projects/:id/deployments
 | `sort`           | string         | no       | Return deployments sorted in `asc` or `desc` order. Default is `asc`                                            |
 | `updated_after`  | datetime       | no       | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
 | `updated_before` | datetime       | no       | Return deployments updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
-| `environment`    | string         | no       | The [name of the environment](../ci/environments/index.md#defining-environments) to filter deployments by       |
+| `environment`    | string         | no       | The [name of the environment](../ci/environments/index.md) to filter deployments by       |
 | `status`         | string         | no       | The status to filter deployments by                                                                             |
 
 The status attribute can be one of the following values:
@@ -281,7 +281,7 @@ POST /projects/:id/deployments
 | Attribute     | Type           | Required | Description                                                                                                     |
 |---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
 | `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `environment` | string         | yes      | The [name of the environment](../ci/environments/index.md#defining-environments) to create the deployment for   |
+| `environment` | string         | yes      | The [name of the environment](../ci/environments/index.md) to create the deployment for                         |
 | `sha`         | string         | yes      | The SHA of the commit that is deployed                                                                          |
 | `ref`         | string         | yes      | The name of the branch or tag that is deployed                                                                  |
 | `tag`         | boolean        | yes      | A boolean that indicates if the deployed ref is a tag (true) or not (false)                                     |

doc/ci/environments/index.md

@@ -25,229 +25,111 @@ If you have a deployment service like [Kubernetes](../../user/project/clusters/i
 associated with your project, you can use it to assist with your deployments.
 You can even access a [web terminal](#web-terminals) for your environment from within GitLab.
 
-## Configuring environments
+## View environments and deployments
 
-Configuring environments involves:
+Prerequisites:
 
-1. Understanding how [pipelines](../pipelines/index.md) work.
-1. Defining environments in your project's [`.gitlab-ci.yml`](../yaml/README.md) file.
-1. Creating a job configured to deploy your application. For example, a deploy job configured with [`environment`](../yaml/README.md#environment) to deploy your application to a [Kubernetes cluster](../../user/project/clusters/index.md).
+- You must have a minimum of [Reporter permission](../../user/permissions.md#project-members-permissions).
 
-The rest of this section illustrates how to configure environments and deployments using
-an example scenario. It assumes you have already:
+To view a list of environments and deployments:
 
-- Created a [project](../../user/project/working_with_projects.md#create-a-project) in GitLab.
-- Set up [a runner](../runners/README.md).
+1. Go to the project's **Operations > Environments** page.
+   The environments are displayed.
 
-In the scenario:
+   ![Environments list](img/environments_list.png)
 
-- We are developing an application.
-- We want to run tests and build our app on all branches.
-- Our default branch is `master`.
-- We deploy the app only when a pipeline on `master` branch is run.
+1. To view a list of deployments for an environment, select the environment name,
+   for example, `staging`.
 
-### Defining environments
+   ![Deployments list](img/deployments_list.png)
 
-You can create environments manually in the web interface, but we recommend
-that you define your environments in the `.gitlab-ci.yml` file. After the first
-deploy, the environments are automatically created.
+Deployments show up in this list only after a deployment job has created them.
 
-Let's consider the following `.gitlab-ci.yml` example:
+## Types of environments
 
-```yaml
-stages:
-  - test
-  - build
-  - deploy
+There are two types of environments:
 
-test:
-  stage: test
-  script: echo "Running tests"
+- Static environments have static names, like `staging` or `production`.
+- Dynamic environments have dynamic names. Dynamic environments
+  are a fundamental part of [Review apps](../review_apps/index.md).
 
-build:
-  stage: build
-  script: echo "Building the app"
+### Create a static environment
+
+You can create an environment and deployment in the UI or in your `.gitlab-ci.yml` file.
+
+In the UI:
+
+1. Go to the project's **Operations > Environments** page.
+1. Select **New environment**.
+1. Enter a name and external URL.
+1. Select **Save**.
+
+In your `.gitlab-ci.yml` file:
 
-deploy_staging:
+1. Specify a name for the environment and optionally, a URL, which determines the deployment URL.
+   For example:
+
+   ```yaml
+   deploy_staging:
      stage: deploy
      script:
        - echo "Deploy to staging server"
      environment:
        name: staging
        url: https://staging.example.com
-  only:
-    - master
-```
-
-We have defined three [stages](../yaml/README.md#stages):
-
-- `test`
-- `build`
-- `deploy`
-
-The jobs assigned to these stages run in this order. If any job fails, then
-the pipeline fails and jobs that are assigned to the next stage don't run.
-
-In our case:
-
-- The `test` job runs first.
-- Then the `build` job.
-- Lastly the `deploy_staging` job.
-
-With this configuration, we:
-
-- Check that the tests pass.
-- Ensure that our app is able to be built successfully.
-- Lastly we deploy to the staging server.
-
-Note that the `environment` keyword defines where the app is deployed. 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.
-
-WARNING:
-Some characters are not allowed in environment names. Use only letters,
-numbers, spaces, and `-`, `_`, `/`, `{`, `}`, or `.`. Also, it must not start nor end with `/`.
-
-In summary, with the above `.gitlab-ci.yml` we have achieved the following:
-
-- All branches run the `test` and `build` jobs.
-- The `deploy_staging` job runs [only](../yaml/README.md#onlyexcept-basic) on the `master`
-  branch, which means all merge requests that are created from branches don't
-  get deployed to the staging server.
-- When a merge request is merged, all jobs run and the `deploy_staging`
-  job deploys our code to a staging server while the deployment
-  is recorded in an environment named `staging`.
-
-#### CI/CD variables and runners
-
-Starting with GitLab 8.15, the environment name is exposed to the runner in
-two forms:
-
-- `$CI_ENVIRONMENT_NAME`. The name given in `.gitlab-ci.yml` (with any CI/CD variables
-  expanded).
-- `$CI_ENVIRONMENT_SLUG`. A "cleaned-up" version of the name, suitable for use in URLs,
-  DNS, etc.
-
-If you change the name of an existing environment, the:
-
-- `$CI_ENVIRONMENT_NAME` variable is updated with the new environment name.
-- `$CI_ENVIRONMENT_SLUG` variable remains unchanged to prevent unintended side
-  effects.
-
-Starting with GitLab 9.3, the environment URL is exposed to the runner via
-`$CI_ENVIRONMENT_URL`. The URL is expanded from either:
+   ```
 
-- `.gitlab-ci.yml`.
-- The external URL from the environment if not defined in `.gitlab-ci.yml`.
+1. Trigger a deployment. (For example, by creating and pushing a commit.)
 
-#### Set dynamic environment URLs after a job finishes
+When the job runs, the environment and deployment are created.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9.
-
-In a job script, you can specify a static [environment URL](#using-the-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.
-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.
-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`.
-
-<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
-For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70jDXtOf4Ig).
+NOTE:
+Some characters cannot be used in environment names.
+For more information about the `environment` keywords, see
+[the `.gitlab-ci.yml` keyword reference](../yaml/README.md#environment).
 
-##### Example of setting dynamic environment URLs
+### Create a dynamic environment
 
-The following example shows a Review App that creates a new environment
-per merge request. The `review` job is triggered by every push, and
-creates or updates an environment named `review/your-branch-name`.
-The environment URL is set to `$DYNAMIC_ENVIRONMENT_URL`:
+To create a dynamic name and URL for an environment, you can use
+[predefined CI/CD variables](../variables/predefined_variables.md). For example:
 
 ```yaml
-review:
-  script:
-    - DYNAMIC_ENVIRONMENT_URL=$(deploy-script)                                 # In script, get the environment URL.
-    - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env    # Add the value to a dotenv file.
-  artifacts:
-    reports:
-      dotenv: deploy.env                                                       # Report back dotenv file to rails.
-  environment:
-    name: review/$CI_COMMIT_REF_SLUG
-    url: $DYNAMIC_ENVIRONMENT_URL                                              # and set the variable produced in script to `environment:url`
-    on_stop: stop_review
-
-stop_review:
+deploy_review:
+  stage: deploy
   script:
-    - ./teardown-environment
-  when: manual
+    - echo "Deploy a review app"
   environment:
-    name: review/$CI_COMMIT_REF_SLUG
-    action: stop
+    name: review/$CI_COMMIT_REF_NAME
+    url: https://$CI_ENVIRONMENT_SLUG.example.com
+  only:
+    - branches
+  except:
+    - master
 ```
 
-As soon as the `review` job finishes, GitLab updates the `review/your-branch-name`
-environment's URL.
-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
-`example.com`, the final result is `https://example.com`.
+In this example:
 
-The assigned URL for the `review/your-branch-name` environment is [visible in the UI](#using-the-environment-url).
+- The `name` is `review/$CI_COMMIT_REF_NAME`. Because the [environment name](../yaml/README.md#environmentname)
+  can contain slashes (`/`), you can use this pattern to distinguish between dynamic and static environments.
+- For the `url`, you could use `$CI_COMMIT_REF_NAME`, but because this value
+  may contain a `/` or other characters that would not be valid in a domain name or URL,
+  use `$CI_ENVIRONMENT_SLUG` instead. The `$CI_ENVIRONMENT_SLUG` variable is guaranteed to be unique.
 
-Note the following:
-
-- `stop_review` doesn't generate a dotenv report artifact, so it doesn't recognize the
-  `DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url:` in the
-  `stop_review` job.
-- If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update
-  the environment URL.
-- If the script that runs in `stop_review` exists only in your repository and therefore can't use
-  `GIT_STRATEGY: none`, configure [pipelines for merge requests](../../ci/merge_request_pipelines/index.md)
-  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).
-
-### Configuring manual deployments
+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.
 
-Adding `when: manual` to an automatically executed job's configuration converts it to
-a job requiring manual action.
+NOTE:
+Some variables cannot be used as environment names or URLs.
+For more information about the `environment` keywords, see
+[the `.gitlab-ci.yml` keyword reference](../yaml/README.md#environment).
 
-To expand on the [previous example](#defining-environments), the following includes
-another job that deploys our app to a production server and is
-tracked by a `production` environment.
+## Configure manual deployments
 
-The `.gitlab-ci.yml` file for this is as follows:
+You can create a job that requires someone to manually start the deployment.
+For example:
 
 ```yaml
-stages:
-  - test
-  - build
-  - deploy
-
-test:
-  stage: test
-  script: echo "Running tests"
-
-build:
-  stage: build
-  script: echo "Building the app"
-
-deploy_staging:
-  stage: deploy
-  script:
-    - echo "Deploy to staging server"
-  environment:
-    name: staging
-    url: https://staging.example.com
-  only:
-    - master
-
 deploy_prod:
   stage: deploy
   script:
@@ -262,106 +144,12 @@ deploy_prod:
 
 The `when: manual` action:
 
-- Exposes a "play" button in the GitLab UI for that job.
-- Means the `deploy_prod` job is only triggered when the "play" button is clicked.
-
-You can find the "play" button in the pipelines, environments, deployments, and jobs views.
-
-| View            | Screenshot                                                                     |
-|:----------------|:-------------------------------------------------------------------------------|
-| Pipelines       | ![Pipelines manual action](../img/environments_manual_action_pipelines.png)       |
-| Single pipeline | ![Pipelines manual action](../img/environments_manual_action_single_pipeline.png) |
-| Environments    | ![Environments manual action](../img/environments_manual_action_environments.png) |
-| Deployments     | ![Deployments manual action](../img/environments_manual_action_deployments.png)   |
-| Jobs            | ![Builds manual action](../img/environments_manual_action_jobs.png)               |
-
-Clicking the play button in any view triggers the `deploy_prod` job. The deployment is recorded as a
-new environment named `production`.
-
-If your environment's name is `production` (all lowercase), it's recorded in
-[Value Stream Analytics](../../user/analytics/value_stream_analytics.md).
-
-### Configuring dynamic environments
-
-Regular environments are good when deploying to "stable" environments like staging or production.
-
-However, for environments for branches other than `master`, dynamic environments
-can be used. Dynamic environments make it possible to create environments on the fly by
-declaring their names dynamically in `.gitlab-ci.yml`.
-
-Dynamic environments are a fundamental part of [Review apps](../review_apps/index.md).
-
-#### Allowed variables
-
-The `name` and `url` keywords for dynamic environments can use most available CI/CD variables,
-including:
-
-- [Predefined CI/CD variables](../variables/README.md#predefined-cicd-variables)
-- [Project and group CI/CD variables](../variables/README.md)
-- [`.gitlab-ci.yml` CI/CD variables](../yaml/README.md#variables)
-
-However, you cannot use variables defined:
-
-- Under `script`.
-- On the runner's side.
-
-There are also other variables that are unsupported in the context of `environment:name`.
-For more information, see [Where variables can be used](../variables/where_variables_can_be_used.md).
-
-#### Example configuration
-
-Runners expose various [predefined CI/CD variables](../variables/predefined_variables.md) when a job runs, so
-you can use them as environment names.
-
-In the following example, the job deploys to all branches except `master`:
-
-```yaml
-deploy_review:
-  stage: deploy
-  script:
-    - echo "Deploy a review app"
-  environment:
-    name: review/$CI_COMMIT_REF_NAME
-    url: https://$CI_ENVIRONMENT_SLUG.example.com
-  only:
-    - branches
-  except:
-    - master
-```
+- Exposes a play button for the job in the GitLab UI.
+- Means the `deploy_prod` job is only triggered when the play button is clicked.
 
-In this example:
+You can find the play button in the pipelines, environments, deployments, and jobs views.
 
-- The job's name is `deploy_review` and it runs on the `deploy` stage.
-- We set the `environment` with the `environment:name` as `review/$CI_COMMIT_REF_NAME`.
-  Since the [environment name](../yaml/README.md#environmentname) can contain slashes (`/`), we can
-  use this pattern to distinguish between dynamic and regular environments.
-- We tell the job to run [`only`](../yaml/README.md#onlyexcept-basic) on branches,
-  [`except`](../yaml/README.md#onlyexcept-basic) `master`.
-
-For the value of:
-
-- `environment:name`, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME`,
-  which receives the value of the branch name.
-- `environment:url`, we want a specific and distinct URL for each branch. `$CI_COMMIT_REF_NAME`
-  may contain a `/` or other characters that would be invalid in a domain name or URL,
-  so we use `$CI_ENVIRONMENT_SLUG` to guarantee that we get a valid URL.
-
-  For example, given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL is something
-  like `https://100-do-the-4f99a2.example.com`. Again, the way you set up
-  the web server to serve these requests is based on your setup.
-
-  We have used `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique. If
-  you're using a workflow like [GitLab Flow](../../topics/gitlab_flow.md), collisions
-  are unlikely and you may prefer environment names to be more closely based on the
-  branch name. In that case, you could use `$CI_COMMIT_REF_NAME` in `environment:url` in
-  the example above: `https://$CI_COMMIT_REF_NAME.example.com`, which would give a URL
-  of `https://100-do-the-thing.example.com`.
-
-You aren't required to use the same prefix or only slashes (`/`) in the dynamic environments' names.
-However, using this format enables the [grouping similar environments](#grouping-similar-environments)
-feature.
-
-### Configuring Kubernetes deployments
+## Configure Kubernetes deployments
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
 
@@ -402,132 +190,114 @@ trace on the deployment job page:
 
 ![Deployment cluster information](../img/environments_deployment_cluster_v12_8.png)
 
-#### Configuring incremental rollouts
+### Configure 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
+## CI/CD variables for environments and deployments
 
-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 helps maintain deployment security and stability.
+When you create an environment, you specify the name and URL.
 
-- [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)
+If you want to use the name or URL in another job, you can use:
 
-### Complete example
+- `$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_URL`. The environment's URL, which was specified in the
+  `.gitlab-ci.yml` file or automatically assigned.
 
-The configuration in this section provides a full development workflow where your app is:
+If you change the name of an existing environment, the:
 
-- Tested.
-- Built.
-- Deployed as a Review App.
-- Deployed to a staging server after the merge request is merged.
-- Finally, able to be manually deployed to the production server.
+- `$CI_ENVIRONMENT_NAME` variable is updated with the new environment name.
+- `$CI_ENVIRONMENT_SLUG` variable remains unchanged to prevent unintended side
+  effects.
 
-The following combines the previous configuration examples, including:
+## Set dynamic environment URLs after a job finishes
 
-- Defining [simple environments](#defining-environments) for testing, building, and deployment to staging.
-- Adding [manual actions](#configuring-manual-deployments) for deployment to production.
-- Creating [dynamic environments](#configuring-dynamic-environments) for deployments for reviewing.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9.
 
-```yaml
-stages:
-  - test
-  - build
-  - deploy
+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.
+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.
+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.
 
-test:
-  stage: test
-  script: echo "Running tests"
+To use this feature, specify the
+[`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
 
-build:
-  stage: build
-  script: echo "Building the app"
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70jDXtOf4Ig).
 
-deploy_review:
-  stage: deploy
-  script:
-    - echo "Deploy a review app"
-  environment:
-    name: review/$CI_COMMIT_REF_NAME
-    url: https://$CI_ENVIRONMENT_SLUG.example.com
-  only:
-    - branches
-  except:
-    - master
+### Example of setting dynamic environment URLs
 
-deploy_staging:
-  stage: deploy
-  script:
-    - echo "Deploy to staging server"
-  environment:
-    name: staging
-    url: https://staging.example.com
-  only:
-    - master
+The following example shows a Review App that creates a new environment
+per merge request. The `review` job is triggered by every push, and
+creates or updates an environment named `review/your-branch-name`.
+The environment URL is set to `$DYNAMIC_ENVIRONMENT_URL`:
 
-deploy_prod:
-  stage: deploy
+```yaml
+review:
   script:
-    - echo "Deploy to production server"
+    - DYNAMIC_ENVIRONMENT_URL=$(deploy-script)                                 # In script, get the environment URL.
+    - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env    # Add the value to a dotenv file.
+  artifacts:
+    reports:
+      dotenv: deploy.env                                                       # Report back dotenv file to rails.
   environment:
-    name: production
-    url: https://example.com
-  when: manual
-  only:
-    - master
-```
-
-A more realistic example would also include copying files to a location where a
-webserver (for example, NGINX) could then access and serve them.
-
-The example below copies the `public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`:
+    name: review/$CI_COMMIT_REF_SLUG
+    url: $DYNAMIC_ENVIRONMENT_URL                                              # and set the variable produced in script to `environment:url`
+    on_stop: stop_review
 
-```yaml
-review_app:
-  stage: deploy
+stop_review:
   script:
-    - rsync -av --delete public /srv/nginx/$CI_COMMIT_REF_SLUG
+    - ./teardown-environment
+  when: manual
   environment:
-    name: review/$CI_COMMIT_REF_NAME
-    url: https://$CI_COMMIT_REF_SLUG.example.com
+    name: review/$CI_COMMIT_REF_SLUG
+    action: stop
 ```
 
-This example requires that NGINX and GitLab Runner are set up on the server this job runs on.
-
-See the [limitations](#limitations) section for some edge cases regarding the naming of your
-branches and Review Apps.
-
-The complete example provides the following workflow to developers:
+As soon as the `review` job finishes, GitLab updates the `review/your-branch-name`
+environment's URL.
+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
+`example.com`, the final result is `https://example.com`.
 
-- Create a branch locally.
-- Make changes and commit them.
-- Push the branch to GitLab.
-- Create a merge request.
+The assigned URL for the `review/your-branch-name` environment is visible in the UI.
 
-Behind the scenes, the runner:
+Note the following:
 
-- Picks up the changes and starts running the jobs.
-- Runs the jobs sequentially as defined in `stages`:
-  - First, run the tests.
-  - If the tests succeed, build the app.
-  - If the build succeeds, the app is deployed to an environment with a name specific to the
-    branch.
+- `stop_review` doesn't generate a dotenv report artifact, so it doesn't recognize the
+  `DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url:` in the
+  `stop_review` job.
+- If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update
+  the environment URL.
+- If the script that runs in `stop_review` exists only in your repository and therefore can't use
+  `GIT_STRATEGY: none`, configure [pipelines for merge requests](../../ci/merge_request_pipelines/index.md)
+  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).
 
-So now, every branch:
+## Deployment safety
 
-- Gets its own environment.
-- Is deployed to its own unique location, with the added benefit of:
-  - Having a [history of deployments](#view-the-deployment-history).
-  - Being able to [roll back changes](#retry-or-roll-back-a-deployment) if needed.
+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.
 
-For more information, see [Using the environment URL](#using-the-environment-url).
+- [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
+## Protected environments
 
 Environments can be "protected", restricting access to them.
 
@@ -538,36 +308,16 @@ For more information, see [Protected environments](protected_environments.md).
 Once environments are configured, GitLab provides many features for working with them,
 as documented below.
 
-### View environments and deployments
-
-Prerequisites:
-
-- You must have a minimum of [Reporter permission](../../user/permissions.md#project-members-permissions).
-
-To view a list of environments and deployment statuses:
-
-- Go to the project's **Operations > Environments** page.
-
-The **Environments** page shows the latest deployments.
-
-- An environment can have multiple deployments. Some deployments may not be listed on the page.
-- Only deploys that happen after your `.gitlab-ci.yml` is properly configured
-  show up in the **Environment** and **Last deployment** lists.
+### Environment rollback
 
-### View the deployment history
+When you roll back a deployment on a specific commit,
+a _new_ deployment is created. This deployment has its own unique job ID.
+It points to the commit you're rolling back to.
 
-GitLab tracks your deployments, so you:
+For the rollback to succeed, the deployment process must be defined in
+the job's `script`.
 
-- Always know what is currently deployed on your servers.
-- Have the full history of your deployments for every environment.
-
-- Go to the project's **Operations > Environments** page.
-
-![Deployments](../img/deployments_view.png)
-
-This view is similar to the **Environments** page, but all deployments are shown.
-
-### Retry or roll back a deployment
+#### Retry or roll back a deployment
 
 If there is a problem with a deployment, you can retry it or roll it back.
 
@@ -575,32 +325,23 @@ To retry or rollback a deployment:
 
 1. Go to the project's **Operations > Environments**.
 1. Select the environment.
-1. In the deployment history list for the environment:
-   - To retry a deployment, select **Retry**.
-   - to roll back to a deployment, next to a previously successful deployment, select **Rollback**.
+1. To the right of the deployment name:
+   - To retry a deployment, select **Re-deploy to environment**.
+   - To roll back to a deployment, next to a previously successful deployment, select **Rollback environment**.
 
-#### What to expect with a rollback
-
-Pressing the **Rollback** button on a specific commit triggers a _new_ deployment with its own
-unique job ID. This new deployment points to the commit you're
-rolling back to.
-
-Note that the defined deployment process in the job's `script` determines whether the rollback
-succeeds.
-
-### Using the environment URL
+### Environment URL
 
 The [environment URL](../yaml/README.md#environmenturl) is exposed in a few
 places within GitLab:
 
-- In a merge request widget as a link:
+- In a merge request as a link:
   ![Environment URL in merge request](../img/environments_mr_review_app.png)
 - In the Environments view as a button:
-  ![Environment URL in environments](../img/environments_available_13_7.png)
+  ![Environment URL in environments](../img/environments_available_13_10.png)
 - In the Deployments view as a button:
   ![Environment URL in deployments](../img/deployments_view.png)
 
-You can see this information in a merge request itself if:
+You can see this information in a merge request if:
 
 - The merge request is eventually merged to the default branch (usually `master`).
 - That branch also deploys to an environment (for example, `staging` or `production`).
@@ -616,19 +357,16 @@ from source files to public pages in the environment set for Review Apps.
 
 ### Stopping an environment
 
-Stopping an environment:
+When you stop an environment:
 
-- Moves it from the list of **Available** environments to the list of **Stopped**
+- It moves from the list of **Available** environments to the list of **Stopped**
   environments on the [**Environments** page](#view-environments-and-deployments).
-- Executes an [`on_stop` action](../yaml/README.md#environmenton_stop), if defined.
-
-This is often used when multiple developers are working on a project at the same time,
-each of them pushing to their own branches, causing many dynamic environments to be created.
+- An [`on_stop` action](../yaml/README.md#environmenton_stop), if defined, is executed.
 
-Starting with GitLab 8.14, dynamic environments stop automatically when their associated branch is
+Dynamic environments stop automatically when their associated branch is
 deleted.
 
-#### Automatically stopping an environment
+#### Stop an environment when a branch is deleted
 
 Environments can be stopped automatically using special configuration.
 
@@ -678,7 +416,7 @@ 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).
 
-#### Environments auto-stop
+#### Stop an environment after a certain time period
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
 
@@ -763,7 +501,7 @@ environment name to see its details and **Delete** it from there.
 You can also delete environments by viewing the details for a
 stopped environment:
 
-  1. Navigate to **Operations > Environments**.
+  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.
@@ -776,7 +514,7 @@ Environments can also be deleted by using the [Environments API](../../api/envir
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) in GitLab 13.2.
 
-By default, GitLab creates a [deployment](#view-the-deployment-history) every time a
+By default, GitLab creates a deployment every time a
 build with the specified environment runs. Newer deployments can also
 [cancel older ones](deployment_safety.md#skip-outdated-deployment-jobs).
 
@@ -801,15 +539,15 @@ build:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7015) in GitLab 8.14.
 
-As documented in [Configuring dynamic environments](#configuring-dynamic-environments), you can
+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.
 
 In short, environments that are named like `type/foo` are all presented under the same
 group, named `type`.
 
-In our [minimal example](#example-configuration), we named the environments `review/$CI_COMMIT_REF_NAME`
-where `$CI_COMMIT_REF_NAME` is the branch name. Here is a snippet of the example:
+If you name the environments `review/$CI_COMMIT_REF_NAME`
+where `$CI_COMMIT_REF_NAME` is the branch name:
 
 ```yaml
 deploy_review:
@@ -820,7 +558,7 @@ deploy_review:
     name: review/$CI_COMMIT_REF_NAME
 ```
 
-In this case, if you visit the **Environments** page and the branches
+If you visit the **Environments** page and the branches
 exist, you should see something like:
 
 ![Environment groups](../img/environments_dynamic_groups.png)

doc/ci/pipelines/index.md

@@ -96,7 +96,7 @@ This table lists the refspecs injected for each pipeline type:
 The refs `refs/heads/<name>` and `refs/tags/<name>` exist in your
 project repository. GitLab generates the special ref `refs/pipelines/<id>` during a
 running pipeline job. This ref can be created even after the associated branch or tag has been
-deleted. It's therefore useful in some features such as [automatically stopping an environment](../environments/index.md#automatically-stopping-an-environment),
+deleted. It's therefore useful in some features such as [automatically stopping an environment](../environments/index.md#stopping-an-environment),
 and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md)
 that might run pipelines after branch deletion.
 
@@ -208,7 +208,7 @@ You can do this straight from the pipeline graph. Just click the play button
 to execute that particular job.
 
 For example, your pipeline might start automatically, but it requires manual action to
-[deploy to production](../environments/index.md#configuring-manual-deployments). In the example below, the `production`
+[deploy to production](../environments/index.md#configure-manual-deployments). In the example below, the `production`
 stage has a job with a manual action.
 
 ![Pipelines example](img/pipelines.png)

doc/ci/review_apps/index.md

@@ -56,7 +56,7 @@ After adding Review Apps to your workflow, you follow the branched Git flow. Tha
 
 ## Configuring Review Apps
 
-Review Apps are built on [dynamic environments](../environments/index.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch.
+Review Apps are built on [dynamic environments](../environments/index.md#create-a-dynamic-environment), which allow you to dynamically create a new environment for each branch.
 
 The process of configuring Review Apps is as follows:
 
@@ -89,7 +89,7 @@ you can copy and paste into `.gitlab-ci.yml` as a starting point. To do so:
 
 ## Review Apps auto-stop
 
-See how to [configure Review Apps environments to expire and auto-stop](../environments/index.md#environments-auto-stop)
+See how to [configure Review Apps environments to expire and auto-stop](../environments/index.md#stop-an-environment-after-a-certain-time-period)
 after a given period of time.
 
 ## Review Apps examples

doc/ci/yaml/README.md

@@ -2322,7 +2322,7 @@ started by a user. You might want to use manual jobs for things like deploying t
 
 To make a job manual, add `when: manual` to its configuration.
 
-Manual jobs can be started from the pipeline, job, [environment](../environments/index.md#configuring-manual-deployments),
+Manual jobs can be started from the pipeline, job, [environment](../environments/index.md#configure-manual-deployments),
 and deployment views.
 
 Manual jobs can be either optional or blocking:
@@ -2562,7 +2562,7 @@ it is set to `manual`, so it needs a [manual action](#whenmanual) from
 the GitLab UI to run.
 
 Also in the example, `GIT_STRATEGY` is set to `none`. If the
-`stop_review_app` job is [automatically triggered](../environments/index.md#automatically-stopping-an-environment),
+`stop_review_app` job is [automatically triggered](../environments/index.md#stopping-an-environment),
 the runner won’t try to check out the code after the branch is deleted.
 
 The example also overwrites global variables. If your `stop` `environment` job depends
@@ -2608,7 +2608,7 @@ When the environment for `review_app` is created, the environment's lifetime is
 Every time the review app is deployed, that lifetime is also reset to `1 day`.
 
 For more information, see
-[the environments auto-stop documentation](../environments/index.md#environments-auto-stop)
+[the environments auto-stop documentation](../environments/index.md#stop-an-environment-after-a-certain-time-period)
 
 #### `environment:kubernetes`
 
@@ -2634,7 +2634,7 @@ environment, using the `production`
 [Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
 
 For more information, see
-[Available settings for `kubernetes`](../environments/index.md#configuring-kubernetes-deployments).
+[Available settings for `kubernetes`](../environments/index.md#configure-kubernetes-deployments).
 
 NOTE:
 Kubernetes configuration is not supported for Kubernetes clusters

doc/development/testing_guide/review_apps.md

@@ -109,7 +109,7 @@ subgraph "CNG-mirror pipeline"
 ### Auto-stopping of Review Apps
 
 Review Apps are automatically stopped 2 days after the last deployment thanks to
-the [Environment auto-stop](../../ci/environments/index.md#environments-auto-stop) feature.
+the [Environment auto-stop](../../ci/environments/index.md#stop-an-environment-after-a-certain-time-period) feature.
 
 If you need your Review App to stay up for a longer time, you can
 [pin its environment](../../ci/environments/index.md#auto-stop-example) or retry the

doc/topics/autodevops/customize.md

@@ -204,7 +204,7 @@ into your project and edit it as needed.
 
 For clusters not managed by GitLab, you can customize the namespace in
 `.gitlab-ci.yml` by specifying
-[`environment:kubernetes:namespace`](../../ci/environments/index.md#configuring-kubernetes-deployments).
+[`environment:kubernetes:namespace`](../../ci/environments/index.md#configure-kubernetes-deployments).
 For example, the following configuration overrides the namespace used for
 `production` deployments:
 

doc/user/project/clusters/index.md

@@ -312,7 +312,7 @@ following command in your deployment job script, for Kubernetes to access the re
 The Kubernetes cluster integration exposes these
 [deployment variables](../../../ci/variables/README.md#deployment-variables) in the
 GitLab CI/CD build environment to deployment jobs. Deployment jobs have
-[defined a target environment](../../../ci/environments/index.md#defining-environments).
+[defined a target environment](../../../ci/environments/index.md).
 
 | Deployment Variable        | Description |
 |----------------------------|-------------|
@@ -345,7 +345,7 @@ You can customize the deployment namespace in a few ways:
 - For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`,
   but the user is responsible for ensuring its existence. You can fully customize
   this value using
-  [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments)
+  [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments)
   in `.gitlab-ci.yml`.
 
 When you customize the namespace, existing environments remain linked to their current
@@ -432,7 +432,7 @@ Reasons for failure include:
 - The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
   privileges required by GitLab.
 - Missing `KUBECONFIG` or `KUBE_TOKEN` deployment variables. To be passed to your job, they must have a matching
-  [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no
+  [`environment:name`](../../../ci/environments/index.md). If your job has no
   `environment:name` set, the Kubernetes credentials are not passed to it.
 
 NOTE:

doc/user/project/deploy_boards.md

@@ -75,7 +75,7 @@ specific environment, there are a lot of use cases. To name a few:
 
 To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should:
 
-1. Have [defined an environment](../../ci/environments/index.md#defining-environments) with a deploy stage.
+1. Have [defined an environment](../../ci/environments/index.md) with a deploy stage.
 
 1. Have a Kubernetes cluster up and running.