From f222d365ab6c14a6cc1c7c1e2cc8a3b28cd401d4 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Wed, 8 Oct 2025 19:40:30 +0900 Subject: [PATCH 1/2] Update details about variables Need to additional clarity on masked and expanded variables, as well as update the setting name. --- doc/ci/variables/_index.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/doc/ci/variables/_index.md b/doc/ci/variables/_index.md index 6ec13fd5abf559..2a342e1d5c8daf 100644 --- a/doc/ci/variables/_index.md +++ b/doc/ci/variables/_index.md @@ -147,7 +147,8 @@ To add or update variables in the project settings: 1. Expand **Variables**. 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. + - **Value**: The value is limited to 10,000 characters, but also bounded by any limits in the + runner's operating system. No other limitations if **Visibility** set to **Visible**. - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). - **Environment scope**: Optional. **All (default)** (`*`), a specific [environment](../environments/_index.md#types-of-environments), or a wildcard [environment scope](../environments/_index.md#limit-the-environment-scope-of-a-cicd-variable). @@ -156,6 +157,8 @@ To add or update variables in the project settings: or [protected tags](../../user/project/protected_tags.md). - **Visibility**: Select **Visible** (default), [**Masked**](#mask-a-cicd-variable), or [**Masked and hidden**](#hide-a-cicd-variable) (only available for new variables). + - **Expand variable reference**: Optional. If selected, the variable can reference another variable. + It is not possible to reference another variable if **Visibility** is set to **Masked** or **Masked and hidden**. After you create a variable, you can use it in the pipeline configuration or in [job scripts](job_scripts.md). @@ -175,13 +178,16 @@ To add a group variable: 1. Expand **Variables**. 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. + - **Value**: The value is limited to 10,000 characters, but also bounded by any limits in the + runner's operating system. No other limitations if **Visibility** set to **Visible**. - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). - **Protect variable** Optional. If selected, the variable is only available in pipelines that run on [protected branches](../../user/project/repository/branches/protected.md) or [protected tags](../../user/project/protected_tags.md). - **Visibility**: Select **Visible** (default), [**Masked**](#mask-a-cicd-variable), or [**Masked and hidden**](#hide-a-cicd-variable) (only available for new variables). + - **Expand variable reference**: Optional. If selected, the variable can reference another variable. + It is not possible to reference another variable if **Visibility** is set to **Masked** or **Masked and hidden**. The group variables that are available in a project are listed in the project's **Settings > CI/CD > Variables** section. Variables from [subgroups](../../user/group/subgroups/_index.md) @@ -227,13 +233,15 @@ To add an instance variable: 1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: The value is limited to 10,000 characters, but also bounded by any limits in the - runner's operating system. + runner's operating system. No other limitations if **Visibility** set to **Visible**. - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). - **Protect variable** Optional. If selected, the variable is only available in pipelines that run on [protected branches](../../user/project/repository/branches/protected.md) or [protected tags](../../user/project/protected_tags.md). - **Visibility**: Select **Visible** (default), [**Masked**](#mask-a-cicd-variable), or [**Masked and hidden**](#hide-a-cicd-variable) (only available for new variables). + - **Expand variable reference**: Optional. If selected, the variable can reference another variable. + It is not possible to reference another variable if **Visibility** is set to **Masked** or **Masked and hidden**. ## CI/CD variable security @@ -428,6 +436,12 @@ job: ## Prevent CI/CD variable expansion +{{< history >}} + +- **Expand variable** option [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/410414) to **Expand variable reference** in GitLab 16.3. + +{{< /history >}} + Expanded variables treat values with the `$` character as a reference to another variable. CI/CD variables are expanded by default. To treat variables with a `$` character as raw strings, disable variable expansion for the variable. @@ -441,7 +455,7 @@ To disable variable expansion for the variable: 1. For the project or group, go to **Settings** > **CI/CD**. 1. Expand **Variables**. 1. Next to the variable you want to do not want expanded, select **Edit**. -1. Clear the **Expand variable** checkbox. +1. Clear the **Expand variable reference** checkbox. 1. Select **Update variable**. If the variable is also [masked](#mask-a-cicd-variable), the value cannot contain the `$` character, -- GitLab From d9dbda316fd35be13c5de10ea1973c373c352924 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Thu, 16 Oct 2025 22:59:54 +0900 Subject: [PATCH 2/2] Update docs regarding variable limitations --- doc/ci/variables/_index.md | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/doc/ci/variables/_index.md b/doc/ci/variables/_index.md index 2a342e1d5c8daf..edc1c6924355b0 100644 --- a/doc/ci/variables/_index.md +++ b/doc/ci/variables/_index.md @@ -148,14 +148,15 @@ To add or update variables in the project settings: 1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: The value is limited to 10,000 characters, but also bounded by any limits in the - runner's operating system. No other limitations if **Visibility** set to **Visible**. + runner's operating system. The value has extra limitations if **Visibility** is set to **Masked** + or **Masked and hidden**. - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). - **Environment scope**: Optional. **All (default)** (`*`), a specific [environment](../environments/_index.md#types-of-environments), or a wildcard [environment scope](../environments/_index.md#limit-the-environment-scope-of-a-cicd-variable). - **Protect variable** Optional. If selected, the variable is only available in pipelines that run on [protected branches](../../user/project/repository/branches/protected.md) or [protected tags](../../user/project/protected_tags.md). - - **Visibility**: Select **Visible** (default), [**Masked**](#mask-a-cicd-variable), + - **Visibility**: Select **Visible**, [**Masked**](#mask-a-cicd-variable) (default), or [**Masked and hidden**](#hide-a-cicd-variable) (only available for new variables). - **Expand variable reference**: Optional. If selected, the variable can reference another variable. It is not possible to reference another variable if **Visibility** is set to **Masked** or **Masked and hidden**. @@ -179,12 +180,13 @@ To add a group variable: 1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: The value is limited to 10,000 characters, but also bounded by any limits in the - runner's operating system. No other limitations if **Visibility** set to **Visible**. + runner's operating system. The value has extra limitations if **Visibility** is set to **Masked** + or **Masked and hidden**. - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). - **Protect variable** Optional. If selected, the variable is only available in pipelines that run on [protected branches](../../user/project/repository/branches/protected.md) or [protected tags](../../user/project/protected_tags.md). - - **Visibility**: Select **Visible** (default), [**Masked**](#mask-a-cicd-variable), + - **Visibility**: Select **Visible**, [**Masked**](#mask-a-cicd-variable) (default), or [**Masked and hidden**](#hide-a-cicd-variable) (only available for new variables). - **Expand variable reference**: Optional. If selected, the variable can reference another variable. It is not possible to reference another variable if **Visibility** is set to **Masked** or **Masked and hidden**. @@ -233,12 +235,13 @@ To add an instance variable: 1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: The value is limited to 10,000 characters, but also bounded by any limits in the - runner's operating system. No other limitations if **Visibility** set to **Visible**. + runner's operating system. The value has extra limitations if **Visibility** is set to **Masked** + or **Masked and hidden**. - **Type**: `Variable` (default) or [`File`](#use-file-type-cicd-variables). - **Protect variable** Optional. If selected, the variable is only available in pipelines that run on [protected branches](../../user/project/repository/branches/protected.md) or [protected tags](../../user/project/protected_tags.md). - - **Visibility**: Select **Visible** (default), [**Masked**](#mask-a-cicd-variable), + - **Visibility**: Select **Visible**, [**Masked**](#mask-a-cicd-variable) (default), or [**Masked and hidden**](#hide-a-cicd-variable) (only available for new variables). - **Expand variable reference**: Optional. If selected, the variable can reference another variable. It is not possible to reference another variable if **Visibility** is set to **Masked** or **Masked and hidden**. @@ -312,9 +315,12 @@ To mask a variable: 1. Expand **Variables**. 1. Next to the variable you want to protect, select **Edit**. 1. Under **Visibility**, select **Mask variable**. +1. Recommended. Clear the [**Expand variable reference**](#prevent-cicd-variable-expansion) checkbox. + If variable expansion is enabled, the only non-alphanumeric characters you can use in + the variable value are: `_`, `:`, `@`, `-`, `+`, `.`, `~`, `=`, `/`, and `~`. + When the setting is disabled, all characters can be used. 1. Select **Update variable**. -The method used to mask variables [limits what can be included in a masked variable](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13784#note_106756757). The value of the variable must: - Be a single line with no spaces. @@ -446,6 +452,13 @@ Expanded variables treat values with the `$` character as a reference to another CI/CD variables are expanded by default. To treat variables with a `$` character as raw strings, disable variable expansion for the variable. +{{< alert type="note" >}} + +If the variable is also [masked](#mask-a-cicd-variable), the value cannot contain the `$` character, +so variable expansion is not possible with masked variables. + +{{< /alert >}} + Prerequisites: - You must have the same role or access level as required to [add a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). @@ -458,9 +471,6 @@ To disable variable expansion for the variable: 1. Clear the **Expand variable reference** checkbox. 1. Select **Update variable**. -If the variable is also [masked](#mask-a-cicd-variable), the value cannot contain the `$` character, -so variable expansion is not possible with masked variables. - ## CI/CD variable precedence {{< history >}} -- GitLab