Add latest changes from gitlab-org/gitlab@master

2 files changed, 82 insertions, 101 deletions

diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md
index f4d155369e9..137bc883072 100644
--- a/doc/ci/environments/index.md
+++ b/doc/ci/environments/index.md
@@ -61,6 +61,12 @@ To search environments by name:
      - For example when the name is `review/test-app`, search term `test` matches `review/test-app`.
      - Also searching with the folder name prefixed like `review/test` matches `review/test-app`.
 
+## CI/CD variables
+
+To customize your environments and deployments, you can use any of the
+[predefined CI/CD variables](../../ci/variables/predefined_variables.md),
+and define custom CI/CD variables.
+
 ## Types of environments
 
 An environment is either static or dynamic:
@@ -123,7 +129,8 @@ deploy_staging:
 
 ### Create a dynamic environment
 
-To create a dynamic environment, you use [CI/CD variables](../variables/index.md) that are unique to each pipeline.
+To create a dynamic environment, you use [CI/CD variables](#cicd-variables) that are
+unique to each pipeline.
 
 Prerequisites:
 
@@ -158,6 +165,79 @@ deploy_review_app:
     - main
 ```
 
+#### Set a dynamic environment URL
+
+Some external hosting platforms generate a random URL for each deployment, for example:
+`https://94dd65b.amazonaws.com/qa-lambda-1234567`. That makes it difficult to reference the URL in
+the `.gitlab-ci.yml` file.
+
+To address this problem, you can configure a deployment job to report back a set of
+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.
+
+To use this feature, specify the
+[`artifacts:reports:dotenv`](../yaml/artifacts_reports.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
+
+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`.
+
+The assigned URL for the `review/your-branch-name` environment is visible in the UI.
+
+<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).
+
+In the following example a review app creates a new environment for each 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`.
+- When 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,
+  expands the `environment:url: $DYNAMIC_ENVIRONMENT_URL` and sets it to the environment
+  URL.
+
+```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:
+  script:
+    - ./teardown-environment
+  when: manual
+  environment:
+    name: review/$CI_COMMIT_REF_SLUG
+    action: stop
+```
+
+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 [merge request pipelines](../../ci/pipelines/merge_request_pipelines.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).
+
+NOTE:
+For Windows runners, you should use the PowerShell `Add-Content` command to write to `.env` files.
+
+```powershell
+Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL"
+```
+
 ### Rename an environment
 
 > - Renaming an environment by using the UI was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68550) in GitLab 14.3.
@@ -268,105 +348,6 @@ job page, it's displayed above the job trace:
 Learn how to release production changes to only a portion of your Kubernetes pods with
 [incremental rollouts](../environments/incremental_rollouts.md).
 
-## CI/CD variables for environments and deployments
-
-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 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.
-
-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.
-
-## Set dynamic environment URLs after a job finishes
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9.
-
-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`.
-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. 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.
-
-To use this feature, specify the
-[`artifacts:reports:dotenv`](../yaml/artifacts_reports.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).
-
-### Example of setting dynamic environment URLs
-
-The following example shows a Review App that creates a new environment
-for each 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`:
-
-```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:
-  script:
-    - ./teardown-environment
-  when: manual
-  environment:
-    name: review/$CI_COMMIT_REF_SLUG
-    action: stop
-```
-
-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`.
-
-The assigned URL for the `review/your-branch-name` environment is visible in the UI.
-
-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 [merge request pipelines](../../ci/pipelines/merge_request_pipelines.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).
-
-NOTE:
-For Windows runners, using `echo` to write to `.env` files may fail. Using the PowerShell `Add-Content`command
-helps in such cases. For example:
-
-```powershell
-Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL"
-```
-
 ## Track newly included merge requests per deployment
 
 GitLab can track newly included merge requests per deployment.
diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md
index 78c9e98c33f..37cb7efdf94 100644
--- a/doc/ci/yaml/artifacts_reports.md
+++ b/doc/ci/yaml/artifacts_reports.md
@@ -189,7 +189,7 @@ GitLab can display the results of one or more reports in:
 The `dotenv` report collects a set of environment variables as artifacts.
 
 The collected variables are registered as runtime-created variables of the job,
-which you can use to [set dynamic environment URLs after a job finishes](../environments/index.md#set-dynamic-environment-urls-after-a-job-finishes).
+which you can use to [set dynamic environment URLs after a job finishes](../environments/index.md#set-a-dynamic-environment-url).
 
 If duplicate environment variables are present in a `dotenv` report: