diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-11-17 14:33:21 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-11-17 14:33:21 +0300 |
commit | 7021455bd1ed7b125c55eb1b33c5a01f2bc55ee0 (patch) | |
tree | 5bdc2229f5198d516781f8d24eace62fc7e589e9 /doc/ci/variables | |
parent | 185b095e93520f96e9cfc31d9c3e69b498cdab7c (diff) |
Add latest changes from gitlab-org/gitlab@15-6-stable-eev15.6.0-rc42
Diffstat (limited to 'doc/ci/variables')
-rw-r--r-- | doc/ci/variables/index.md | 111 | ||||
-rw-r--r-- | doc/ci/variables/predefined_variables.md | 2 | ||||
-rw-r--r-- | doc/ci/variables/where_variables_can_be_used.md | 4 |
3 files changed, 26 insertions, 91 deletions
diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index 7ad42aaf96b..97707c603bd 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -106,7 +106,7 @@ job1: Variables saved in the `.gitlab-ci.yml` file should store only non-sensitive project configuration, like a `RAILS_ENV` or `DATABASE_URL` variable. These variables are -visible in the repository. Store sensitive variables containing secrets, keys, and so on +visible in the repository. Store sensitive variables containing values like secrets or keys in project settings. Variables saved in the `.gitlab-ci.yml` file are also available in [service containers](../docker/using_docker_images.md). @@ -161,7 +161,7 @@ in the project settings, not in the `.gitlab-ci.yml` file. To add or update variables in the project settings: 1. Go to your project's **Settings > CI/CD** and expand the **Variables** section. -1. Select the **Add Variable** button and fill in the details: +1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. @@ -203,7 +203,7 @@ Use group variables to store secrets like passwords, SSH keys, and credentials, To add a group variable: 1. In the group, go to **Settings > CI/CD**. -1. Select the **Add Variable** button and fill in the details: +1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. @@ -241,7 +241,7 @@ To add an instance variable: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD** and expand the **Variables** section. -1. Select the **Add variable** button, and fill in the details: +1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: In [GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), @@ -255,8 +255,6 @@ To add an instance variable: ### CI/CD variable types -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11. - All predefined CI/CD variables and variables defined in the `.gitlab-ci.yml` file are `Variable` type. Project, group and instance CI/CD variables can be `Variable` or `File` type. @@ -333,7 +331,7 @@ job1: ### Mask a CI/CD variable -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13784) in GitLab 11.10 +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330650) in GitLab 13.12, the `~` character can be used in masked variables. You can mask a project, group, or instance CI/CD variable so the value of the variable does not display in job logs. @@ -352,20 +350,24 @@ The value of the variable must: - Be a single line. - Be 8 characters or longer, consisting only of: - Characters from the Base64 alphabet (RFC4648). - - The `@` and `:` characters (In [GitLab 12.2 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/63043)). - - The `.` character (In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29022)). - - The `~` character (In [GitLab 13.12 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61517)). + - The `@`, `:`, `.`, or `~` characters. - Not match the name of an existing predefined or custom CI/CD variable. -NOTE: -Masking a CI/CD variable is not a guaranteed way to prevent malicious users from accessing -variable values. To make variables more secure, you can [use external secrets](../secrets/index.md). - WARNING: -Due to a technical limitation, masked variables that are more than 4 KiB in length are not recommended. Printing such -a large value to the trace log has the potential to be [revealed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28128). -When using GitLab Runner 14.2, only the tail of the variable, characters beyond 4KiB in length, have the potential to -be revealed. +Masking a CI/CD variable is not a guaranteed way to prevent malicious users from +accessing variable values. The masking feature is "best-effort" and there to +help when a variable is accidentally revealed. To make variables more secure, +consider using [external secrets](../secrets/index.md) and [file type variables](#cicd-variable-types) +to prevent commands such as `env`/`printenv` from printing secret variables. + +Runner versions implement masking in different ways, some with technical +limitations. Below is a table of such limitations. + +| Version from | Version to | Limitations | +| ------------ | ---------- | ------ | +| v11.9.0 | v14.1.0 | Masking of large secrets (greater than 4 KiB) could potentially be [revealed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28128). No sensitive URL parameter masking. | +| v14.2.0 | v15.3.0 | The tail of a large secret (greater than 4 KiB) could potentially be [revealed](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28128). No sensitive URL parameter masking. | +| v15.7.0 | | Potential for secrets to be revealed when `CI_DEBUG_SERVICES` is enabled. For details, read about [service container logging](../services/index.md#capturing-service-container-logs). | ### Protected CI/CD variables @@ -506,7 +508,7 @@ job_name: # - 'dir env:' # Use this for PowerShell ``` -Example job log output: +Example job log output (truncated): ```shell export CI_JOB_ID="50" @@ -528,31 +530,6 @@ export CI_PROJECT_ID="34" export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-foss" export CI_PROJECT_NAME="gitlab-foss" export CI_PROJECT_TITLE="GitLab FOSS" -export CI_PROJECT_DESCRIPTION="GitLab FOSS is a read-only mirror of GitLab, with all proprietary code removed." -export CI_PROJECT_NAMESPACE="gitlab-org" -export CI_PROJECT_ROOT_NAMESPACE="gitlab-org" -export CI_PROJECT_PATH="gitlab-org/gitlab-foss" -export CI_PROJECT_URL="https://example.com/gitlab-org/gitlab-foss" -export CI_REGISTRY="registry.example.com" -export CI_REGISTRY_IMAGE="registry.example.com/gitlab-org/gitlab-foss" -export CI_REGISTRY_USER="gitlab-ci-token" -export CI_REGISTRY_PASSWORD="[masked]" -export CI_RUNNER_ID="10" -export CI_RUNNER_DESCRIPTION="my runner" -export CI_RUNNER_TAGS="docker, linux" -export CI_SERVER="yes" -export CI_SERVER_URL="https://example.com" -export CI_SERVER_HOST="example.com" -export CI_SERVER_PORT="443" -export CI_SERVER_PROTOCOL="https" -export CI_SERVER_NAME="GitLab" -export CI_SERVER_REVISION="70606bf" -export CI_SERVER_VERSION="8.9.0" -export CI_SERVER_VERSION_MAJOR="8" -export CI_SERVER_VERSION_MINOR="9" -export CI_SERVER_VERSION_PATCH="0" -export GITLAB_USER_EMAIL="user@example.com" -export GITLAB_USER_ID="42" ... ``` @@ -776,8 +753,6 @@ explains if the integration has any deployment variables available. ## Auto DevOps environment variables -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/49056) in GitLab 11.7. - You can configure [Auto DevOps](../../topics/autodevops/index.md) to pass CI/CD variables to a running application. @@ -817,7 +792,7 @@ job_name: Example output (truncated): -```shell +```plaintext ... export CI_SERVER_TLS_CA_FILE="/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE" if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then @@ -885,48 +860,6 @@ if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then ++ CI_PROJECT_ID=17893 ++ export CI_PROJECT_NAME=ci-debug-trace ++ CI_PROJECT_NAME=ci-debug-trace -++ export CI_PROJECT_TITLE='GitLab FOSS' -++ CI_PROJECT_TITLE='GitLab FOSS' -++ export CI_PROJECT_DESCRIPTION='GitLab FOSS is a read-only mirror of GitLab, with all proprietary code removed.' -++ CI_PROJECT_DESCRIPTION='GitLab FOSS is a read-only mirror of GitLab, with all proprietary code removed.' -++ export CI_PROJECT_PATH=gitlab-examples/ci-debug-trace -++ CI_PROJECT_PATH=gitlab-examples/ci-debug-trace -++ export CI_PROJECT_PATH_SLUG=gitlab-examples-ci-debug-trace -++ CI_PROJECT_PATH_SLUG=gitlab-examples-ci-debug-trace -++ export CI_PROJECT_NAMESPACE=gitlab-examples -++ CI_PROJECT_NAMESPACE=gitlab-examples -++ export CI_PROJECT_ROOT_NAMESPACE=gitlab-examples -++ CI_PROJECT_ROOT_NAMESPACE=gitlab-examples -++ export CI_PROJECT_URL=https://gitlab.com/gitlab-examples/ci-debug-trace -++ CI_PROJECT_URL=https://gitlab.com/gitlab-examples/ci-debug-trace -++ export CI_PROJECT_VISIBILITY=public -++ CI_PROJECT_VISIBILITY=public -++ export CI_PROJECT_REPOSITORY_LANGUAGES= -++ CI_PROJECT_REPOSITORY_LANGUAGES= -++ export CI_PROJECT_CLASSIFICATION_LABEL= -++ CI_PROJECT_CLASSIFICATION_LABEL= -++ export CI_DEFAULT_BRANCH=main -++ CI_DEFAULT_BRANCH=main -++ export CI_REGISTRY=registry.gitlab.com -++ CI_REGISTRY=registry.gitlab.com -++ export CI_API_V4_URL=https://gitlab.com/api/v4 -++ CI_API_V4_URL=https://gitlab.com/api/v4 -++ export CI_PIPELINE_IID=123 -++ CI_PIPELINE_IID=123 -++ export CI_PIPELINE_SOURCE=web -++ CI_PIPELINE_SOURCE=web -++ export CI_CONFIG_PATH=.gitlab-ci.yml -++ CI_CONFIG_PATH=.gitlab-ci.yml -++ export CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_COMMIT_SHORT_SHA=dd648b2e -++ CI_COMMIT_SHORT_SHA=dd648b2e -++ export CI_COMMIT_BEFORE_SHA=0000000000000000000000000000000000000000 -++ CI_COMMIT_BEFORE_SHA=0000000000000000000000000000000000000000 -++ export CI_COMMIT_REF_NAME=main -++ CI_COMMIT_REF_NAME=main -++ export CI_COMMIT_REF_SLUG=main -++ CI_COMMIT_REF_SLUG=main ... ``` diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 606847ee756..852110a1415 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -46,6 +46,7 @@ as it can cause the pipeline to behave unexpectedly. | `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | The unique ID of build execution in a single executor and project. | | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | | `CI_DEBUG_TRACE` | all | 1.7 | `true` if [debug logging (tracing)](index.md#debug-logging) is enabled. | +| `CI_DEBUG_SERVICES` | 15.7 | 15.7 | `true` if [service container logging](../services/index.md#capturing-service-container-logs) is enabled. | | `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the project's default branch. | | `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | | `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` | 14.3 | all | The direct group image prefix for pulling images through the Dependency Proxy. | @@ -89,7 +90,6 @@ as it can cause the pipeline to behave unexpectedly. | `CI_PIPELINE_TRIGGERED` | all | all | `true` if the job was [triggered](../triggers/index.md). | | `CI_PIPELINE_URL` | 11.1 | 0.5 | The URL for the pipeline details. | | `CI_PIPELINE_CREATED_AT` | 13.10 | all | The UTC datetime when the pipeline was created, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. | -| `CI_PROJECT_CONFIG_PATH` | 13.8 to 13.12 | all | [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/322807) in GitLab 14.0. Use `CI_CONFIG_PATH`. | | `CI_PROJECT_DIR` | all | all | The full path the repository is cloned to, and where the job runs from. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see the [Advanced GitLab Runner configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | | `CI_PROJECT_ID` | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | | `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 7e5451658f2..c8436fc044d 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -36,13 +36,15 @@ There are two places defined variables can be used. On the: | [`include`](../yaml/index.md#include) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. <br/><br/>See [Use variables with include](../yaml/includes.md#use-variables-with-include) for more information on supported variables. | | [`only:variables`](../yaml/index.md#onlyvariables--exceptvariables) | no | Not applicable | The variable must be in the form of `$variable`. Not supported are 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`](../yaml/index.md#resource_group) | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/>- `CI_ENVIRONMENT_URL`<br/>- [Persisted variables](#persisted-variables). | +| [`rules:exists`](../yaml/index.md#rulesexists) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. | | [`rules:if`](../yaml/index.md#rulesif) | no | Not applicable | The variable must be in the form of `$variable`. Not supported are 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). | | [`script`](../yaml/index.md#script) | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment). | | [`services:name`](../yaml/index.md#services) | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | | [`services`](../yaml/index.md#services) | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | | [`tags`](../yaml/index.md#tags) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35742) in GitLab 14.1. | -| [`trigger` and `trigger:project`](../yaml/index.md#trigger) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367660) in GitLab 15.3. | +| [`trigger` and `trigger:project`](../yaml/index.md#trigger) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. Variable expansion for `trigger:project` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367660) in GitLab 15.3. | | [`variables`](../yaml/index.md#variables) | yes | GitLab/Runner | The variable expansion is first made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab, and then any unrecognized or unavailable variables are expanded by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | +| [`workflow:name`](../yaml/index.md#workflowname) | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.<br/><br/>Supported are all variables available in `workflow`:<br/>- Project/Group variables.<br/>- Global `variables` and `workflow:rules:variables` (when matching the rule).<br/>- Variables inherited from parent pipelines.<br/>- Variables from triggers.<br/>- Variables from pipeline schedules.<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml`, variables defined in jobs, or [Persisted variables](#persisted-variables). | ### `config.toml` file |