From c50e042a392687730db9b8c2607883485b258ae4 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Mon, 22 May 2023 21:08:01 +0000 Subject: Add latest changes from gitlab-org/gitlab@master --- doc/ci/environments/index.md | 181 ++++++++++++++++++--------------------- doc/ci/yaml/artifacts_reports.md | 2 +- 2 files changed, 82 insertions(+), 101 deletions(-) (limited to 'doc/ci') 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. + + +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`. - - -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: -- cgit v1.2.3