diff options
Diffstat (limited to 'doc/ci/variables')
-rw-r--r-- | doc/ci/variables/README.md | 93 | ||||
-rw-r--r-- | doc/ci/variables/deprecated_variables.md | 1 | ||||
-rw-r--r-- | doc/ci/variables/predefined_variables.md | 5 | ||||
-rw-r--r-- | doc/ci/variables/where_variables_can_be_used.md | 12 |
4 files changed, 44 insertions, 67 deletions
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 1a982fa4e19..9c8fb994bf7 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -12,10 +12,11 @@ affect the way running processes behave on an operating system. Environment variables are part of the environment in which a process runs. -For example, a running process can query the value of the -`TEMP` environment variable to discover a suitable location -to store temporary files, or to define a `URL` for a database -that can be reused in different scripts. +For example, a running process could: + +- Use the value of a `TEMP` environment variable to know the correct location + to store temporary files. +- Use a `DATABASE_URL` variable for the URL to a database that can be reused in different scripts. Variables are useful for customizing your jobs in GitLab CI/CD. When you use variables, you don't have to hard-code values. @@ -62,22 +63,6 @@ job `test_variable`, which is `test`: ![Output `$CI_JOB_STAGE`](img/ci_job_stage_output_example.png) -As another example, let's say you're using your own GitLab -instance and you want to know what domain your GitLab Pages are -served under. You can call it by using the predefined -variable `$CI_PAGES_DOMAIN` in your script: - -```yaml -pages: - script: - - ... - - echo $CI_PAGES_DOMAIN -``` - -For GitLab.com users, the output is `gitlab.io`. For your -private instance, the output is whatever your sysadmin has -defined. - ## Custom environment variables When you need a specific custom environment variable, you can @@ -103,8 +88,8 @@ variables: You can then call its value in your script: ```yaml - script: - - echo "$TEST" +script: + - echo "$TEST" ``` For more details, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined-variables). @@ -181,8 +166,8 @@ You can use tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/user and [`kubectl`](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable) to customize your configuration by using **File** type variables. -In the past, a common pattern was to read the value of a CI variable, save it in a file, and then -use the newly created file in your script: +Previously, a common pattern was to read the value of a CI variable, save it in a file, and then +use that file in your script: ```shell # Read certificate stored in $KUBE_CA_PEM variable and save it in a new file @@ -258,7 +243,7 @@ Some variables are listed in the UI so you can choose them more quickly. | `AWS_DEFAULT_REGION` | Any | 12.10 | | `AWS_SECRET_ACCESS_KEY` | Any | 12.10 | -NOTE: **Note:** +CAUTION: **Caution:** When you store credentials, there are security implications. If you are using AWS keys, for example, follow their [best practices](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html). @@ -288,11 +273,11 @@ job_name: ### PowerShell -To access environment variables in a **Windows PowerShell** environment, prefix -the variable name with (`$env:`). For environment variables set by GitLab CI, including those set by [`variables`](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/ci/yaml/README.md#variables) -parameter, they can also be accessed by prefixing the variable name with (`$`) -as of [GitLab Runner 1.0.0](https://gitlab.com/gitlab-org/gitlab-runner/-/commit/abc44bb158008cd3a49c0d8173717c38dadb29ae#47afd7e8f12afdb8f0246262488f24e6dd071a22). -System set environment variables however must be accessed using (`$env:`). +To access variables in a **Windows PowerShell** environment, including system set +environment variables, prefix the variable name with (`$env:`). Environment variables +set by GitLab CI can also be accessed by prefixing the variable name with (`$`) with +[GitLab Runner 1.0.0](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/68) +and later. ```yaml job_name: @@ -386,9 +371,6 @@ export GITLAB_USER_ID="42" ## `.gitlab-ci.yml` defined variables -NOTE: **Note:** -This feature requires GitLab Runner 0.5.0 or higher and GitLab 7.14 or higher. - You can add variables that are set in the build environment to `.gitlab-ci.yml`. These variables are saved in the repository, and they are meant to store non-sensitive project configuration, like `RAILS_ENV` or @@ -428,10 +410,12 @@ script: > Introduced in GitLab 9.4. -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](../secrets/index.md), we recommend using group environment variables to store secrets like passwords, SSH keys, and credentials. +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`). They are securely passed to GitLab Runner, which makes them available during a pipeline run. + +We recommend using group environment variables to store secrets (like passwords, SSH keys, and credentials) for Premium users who: + +- Do **not** use an external key store. +- Use GitLab's [integration with HashiCorp Vault](../secrets/index.md). Group-level variables can be added by: @@ -452,8 +436,7 @@ Once you set them, they are available for all subsequent pipelines. Any group-le Instance variables are useful for no longer needing to manually enter the same credentials repeatedly for all your projects. Instance-level variables are available to all projects and groups on the instance. -NOTE: **Note:** -The maximum number of instance-level variables is [planned to be 25](https://gitlab.com/gitlab-org/gitlab/-/issues/216097). +In GitLab 13.1 and later, the [maximum number of instance-level variables is 25](https://gitlab.com/gitlab-org/gitlab/-/issues/216097). You can define instance-level variables via the UI or [API](../../api/instance_level_ci_variables.md). @@ -463,7 +446,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**: [In GitLab 13.3 and later](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). @@ -566,12 +549,11 @@ variables take precedence over those defined in `.gitlab-ci.yml`. Variable names are limited by the underlying shell used to execute scripts (see [available shells](https://docs.gitlab.com/runner/shells/index.html). Each shell has its own unique set of reserved variable names. -You also want to keep in mind the [scope of environment variables](where_variables_can_be_used.md) to ensure a variable is defined in the scope -in which you wish to use it. +Keep in mind the [scope of environment variables](where_variables_can_be_used.md) to ensure a variable is defined in the scope in which you wish to use it. ## Where variables can be used -Click [here](where_variables_can_be_used.md) for a section that describes where and how the different types of variables can be used. +[This section](where_variables_can_be_used.md) describes where and how the different types of variables can be used. ## Advanced use @@ -609,8 +591,8 @@ then available as environment variables on the running application container. CAUTION: **Caution:** -Variables with multi-line values are not currently supported due to -limitations with the current Auto DevOps scripting environment. +Variables with multi-line values are not supported due to +limitations with the Auto DevOps scripting environment. ### Override a variable by manually running a pipeline @@ -701,9 +683,10 @@ Examples: - `$VARIABLE == ""` - `$VARIABLE != ""` (introduced in GitLab 11.11) -If you want to check whether a variable is defined, but is empty, you can -simply compare it against an empty string, like `$VAR == ''` or non-empty -string `$VARIABLE != ""`. +To check if a variable is defined but empty, compare it to: + +- An empty string: `$VARIABLE == ''` +- A non-empty string: `$VARIABLE != ""` #### Comparing two variables @@ -719,9 +702,8 @@ of these variables. Example: `$STAGING` -If you only want to create a job when there is some variable present, -which means that it is defined and non-empty, you can simply use -variable name as an expression, like `$STAGING`. If `$STAGING` variable +To create a job when there is some variable present, meaning it is defined and non-empty, +use the variable name as an expression, like `$STAGING`. If the `$STAGING` variable is defined, and is non empty, expression evaluates to `true`. `$STAGING` value needs to be a string, with length higher than zero. Variable that contains only whitespace characters is not an empty variable. @@ -785,7 +767,7 @@ Examples: ##### Enable or disable parenthesis support for variables **(CORE ONLY)** -The feature is currently deployed behind a feature flag that is **enabled by default**. +The feature is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can opt to disable it for your instance. @@ -820,8 +802,7 @@ NOTE: **Note:** The available regular expression syntax is limited. See [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35438) for more details. -If needed, you can use a test pipeline to determine whether a regular expression will -work in a variable. The example below tests the `^mast.*` regular expression directly, +If needed, you can use a test pipeline to determine whether a regular expression works in a variable. The example below tests the `^mast.*` regular expression directly, as well as from within a variable: ```yaml @@ -856,9 +837,7 @@ from being leaked into the log unless your script writes them to the screen. If a job isn't working as expected, this can make the problem difficult to investigate; in these cases, you can enable debug tracing in `.gitlab-ci.yml`. -Available on GitLab Runner v1.7+, this feature enables the shell's execution -log, resulting in a verbose job log listing all commands that were run, -variables that were set, and so on. +Available on GitLab Runner v1.7+, this feature enables the shell's execution log. This results in a verbose job log listing all commands that were run, variables that were set, and so on. Before enabling this, you should ensure jobs are visible to [team members only](../../user/permissions.md#project-features). You should diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md index 94ec8439605..71e2b5b2e44 100644 --- a/doc/ci/variables/deprecated_variables.md +++ b/doc/ci/variables/deprecated_variables.md @@ -16,7 +16,6 @@ To follow conventions of naming across GitLab, and to further move away from the `build` term and toward `job`, some [CI/CD environment variables](README.md#predefined-environment-variables) were renamed for GitLab 9.0 release. -NOTE: **Note:** Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are strongly advised to use the new variables as we will remove the old ones in future GitLab releases.** diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 915041b71a6..08aaacd2620 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -69,7 +69,8 @@ Kubernetes-specific environment variables are detailed in the | `CI_JOB_MANUAL` | 8.12 | all | The flag to indicate that job was manually started | | `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_STATUS` | all | 13.5 | The state of the job as each runner stage is executed. Use with [`after_script`](../yaml/README.md#before_script-and-after_script) where `CI_JOB_STATUS` can be either: `success`, `failed` or `canceled`. | +| `CI_JOB_TOKEN` | 9.0 | 1.2 | Token used for authenticating with [a few API endpoints](../../api/README.md#gitlab-ci-job-token) and downloading [dependent repositories](../../user/project/new_ci_build_permissions_model.md#dependent-repositories). The token is valid as long as the job is running. | | `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) | @@ -104,7 +105,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_PROJECT_ID` | all | all | The unique ID of the current project that GitLab CI/CD uses internally | | `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project that is currently being built. For example, if the project URL is `gitlab.example.com/group-name/project-1`, the `CI_PROJECT_NAME` would be `project-1`. | | `CI_PROJECT_NAMESPACE` | 8.10 | 0.5 | The project namespace (username or group name) that is currently being built | -| `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The **root** project namespace (username or group name) that is currently being built. For example, if `CI_PROJECT_NAME` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` would be `root-group`. | +| `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The **root** project namespace (username or group name) that is currently being built. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` would be `root-group`. | | `CI_PROJECT_PATH` | 8.10 | 0.5 | The namespace with project name | | `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` lowercased and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. | | `CI_PROJECT_REPOSITORY_LANGUAGES` | 12.3 | all | Comma-separated, lowercased list of the languages used in the repository (e.g. `ruby,javascript,html,css`) | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 330b960ca9a..b4236ca34c2 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -38,15 +38,14 @@ 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 [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 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) | +You can read more about `config.toml` in the [GitLab Runner docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + ## Expansion mechanisms There are three expansion mechanisms: @@ -104,10 +103,6 @@ These restrictions are because `after_script` scripts are executed in a ## Persisted variables -NOTE: **Note:** -Some of the persisted variables contain tokens and cannot be used by some definitions -due to security reasons. - The following variables are known as "persisted": - `CI_PIPELINE_ID` @@ -130,6 +125,9 @@ They are: - For definitions where the ["Expansion place"](#gitlab-ciyml-file) is GitLab. - In the `only` and `except` [variables expressions](README.md#environment-variables-expressions). +Some of the persisted variables contain tokens and cannot be used by some definitions +due to security reasons. + ## Variables with an environment scope Variables defined with an environment scope are supported. Given that |