diff options
Diffstat (limited to 'doc/ci/variables/index.md')
| -rw-r--r-- | doc/ci/variables/index.md | 69 |
1 files changed, 54 insertions, 15 deletions
diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index acc3489143a..7ce58b015ca 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -81,7 +81,7 @@ to execute scripts. Each shell has its own set of reserved variable names. Make sure each variable is defined for the [scope you want to use it in](where_variables_can_be_used.md). By default, pipelines from forked projects can't access CI/CD variables in the parent project. -If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project), +If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project), all variables become available to the pipeline. ### Create a custom CI/CD variable in the `.gitlab-ci.yml` file @@ -394,7 +394,7 @@ runs on a [protected branch](../../user/project/protected_branches.md) or Review all merge requests that introduce changes to the `.gitlab-ci.yml` file before you: -- [Run a pipeline in the parent project for a merge request submitted from a forked project](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project). +- [Run a pipeline in the parent project for a merge request submitted from a forked project](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project). - Merge the changes. The following example shows malicious code in a `.gitlab-ci.yml` file: @@ -554,37 +554,45 @@ export GITLAB_USER_ID="42" > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22638) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217834) in GitLab 13.1. -You can pass environment variables from one job to another job in a later stage. +You can pass environment variables from one job to another job in a later stage +through variable inheritance. These variables cannot be used as CI/CD variables to configure a pipeline, but they can be used in job scripts. 1. In the job script, save the variable as a `.env` file. + - The format of the file must be one variable definition per line. + - Each defined line must be of the form `VARIABLE_NAME=ANY VALUE HERE`. + - Values can be wrapped in quotes, but cannot contain newline characters. 1. Save the `.env` file as an [`artifacts:reports:dotenv`](../yaml/artifacts_reports.md#artifactsreportsdotenv) artifact. -1. Set a job in a later stage to receive the artifact by using the [`dependencies`](../yaml/index.md#dependencies) - or the [`needs`](../yaml/index.md#needs) keywords. -1. The later job can then [use the variable in scripts](#use-cicd-variables-in-job-scripts). +1. Jobs in later stages can then [use the variable in scripts](#use-cicd-variables-in-job-scripts). -For example, with the [`dependencies`](../yaml/index.md#dependencies) keyword: +Inherited variables [take precedence](#cicd-variable-precedence) over +certain types of new variable definitions such as job defined variables. ```yaml build: stage: build script: - - echo "BUILD_VERSION=hello" >> build.env + - echo "BUILD_VARIABLE=value_from_build_job" >> build.env artifacts: reports: dotenv: build.env deploy: stage: deploy + variables: + BUILD_VARIABLE: value_from_deploy_job script: - - echo "$BUILD_VERSION" # Output is: 'hello' - dependencies: - - build + - echo "$BUILD_VARIABLE" # Output is: 'value_from_build_job' due to precedence ``` -For example, with the [`needs:artifacts`](../yaml/index.md#needsartifacts) keyword: +The [`dependencies`](../yaml/index.md#dependencies) or +[`needs`](../yaml/index.md#needs) keywords can be used to control +which jobs receive inherited values. + +To have no inherited dotenv environment variables, pass an empty `dependencies` or +`needs` list, or pass [`needs:artifacts`](../yaml/index.md#needsartifacts) as `false` ```yaml build: @@ -595,15 +603,46 @@ build: reports: dotenv: build.env -deploy: +deploy_one: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is: 'hello' + dependencies: + - build + +deploy_two: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is empty + dependencies: [] + +deploy_three: stage: deploy script: - echo "$BUILD_VERSION" # Output is: 'hello' needs: - - job: build - artifacts: true + - build + +deploy_four: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is: 'hello' + needs: + job: build + artifacts: true + +deploy_five: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is empty + needs: + job: build + artifacts: false ``` +[Multi-project pipelines](../pipelines/multi_project_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline-by-using-variable-inheritance) +can also inherit variables from their upstream pipelines. + ## CI/CD variable precedence You can use CI/CD variables with the same name in different places, but the values |