From 80361d600b0c21056070f0ed6ff11dc82f07165c Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Wed, 8 Oct 2025 19:40:30 +0900
Subject: [PATCH 1/8] 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 501aecb3899995..d86c1d4af61eeb 100644
--- a/doc/ci/variables/_index.md
+++ b/doc/ci/variables/_index.md
@@ -132,13 +132,16 @@ 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),
      or a wildcard environment scope.
    - **Protect variable** Optional. If selected, the variable is only available in pipelines
      that run on protected branches or tags.
    - **Visibility**: Select **Visible** (default), **Masked**, or **Masked and hidden**.
+   - **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**.
 
 Alternatively, project variables can be added [by using the API](../../api/project_level_variables.md).
 
@@ -157,11 +160,14 @@ 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 or tags.
    - **Visibility**: Select **Visible** (default), **Masked**, **Masked and hidden**.
+   - **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 are recursively inherited.
@@ -208,11 +214,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.
+     runner's operating system. No other limitations if **Visibility** set to **Visible**.
    - **Type**: `Variable` (default) or `File`.
    - **Protect variable** Optional. If selected, the variable is only available in pipelines
      that run on protected branches or tags.
    - **Visibility**: Select **Visible** (default), **Masked**, or **Masked and hidden**.
+   - **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**.
 
 Alternatively, instance variables can be added [by using the API](../../api/instance_level_ci_variables.md).
 
@@ -404,6 +412,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.
@@ -417,7 +431,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, the value cannot contain the `$` character,
-- 
GitLab


From 4f59827b437331186ca5f0cfce8858b6e3f7b484 Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Thu, 16 Oct 2025 22:59:54 +0900
Subject: [PATCH 2/8] Update docs regarding variable limitations

---
 doc/ci/variables/_index.md | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/doc/ci/variables/_index.md b/doc/ci/variables/_index.md
index d86c1d4af61eeb..046a0a0af5230f 100644
--- a/doc/ci/variables/_index.md
+++ b/doc/ci/variables/_index.md
@@ -133,7 +133,8 @@ 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),
      or a wildcard environment scope.
@@ -161,7 +162,8 @@ 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 or tags.
@@ -290,6 +292,10 @@ 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 value of the variable must:
@@ -422,6 +428,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).
@@ -434,9 +447,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, the value cannot contain the `$` character,
-so variable expansion is not possible with masked variables.
-
 ## CI/CD variable precedence
 
 {{< history >}}
-- 
GitLab


From a4dabf1e1df79f117c81a143e43375be814b1270 Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Thu, 16 Oct 2025 23:23:52 +0900
Subject: [PATCH 3/8] Set variable setting as default disabled

The masked setting for CI/CD variables defaults to enabled,
which in incompatible with variable expansion. This commit
sets expansion to default disabled.

Changelog: changed
---
 .../javascripts/ci/ci_variable_list/constants.js    |  2 +-
 doc/ci/jobs/job_control.md                          |  2 +-
 doc/ci/pipelines/_index.md                          |  2 +-
 doc/ci/variables/_index.md                          | 13 +++++++------
 .../components/ci_variable_drawer_spec.js           |  2 +-
 5 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/app/assets/javascripts/ci/ci_variable_list/constants.js b/app/assets/javascripts/ci/ci_variable_list/constants.js
index 3966489e3c166c..79006363844362 100644
--- a/app/assets/javascripts/ci/ci_variable_list/constants.js
+++ b/app/assets/javascripts/ci/ci_variable_list/constants.js
@@ -35,7 +35,7 @@ export const defaultVariableState = {
   masked: true,
   hidden: false,
   protected: false,
-  raw: false,
+  raw: true,
   value: '',
   variableType: variableTypes.envType,
 };
diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md
index 2ce758efd3a2b6..b56b2fb861bc94 100644
--- a/doc/ci/jobs/job_control.md
+++ b/doc/ci/jobs/job_control.md
@@ -90,7 +90,7 @@ Consider this visibility when entering sensitive information as manual job varia
 
 If you add a variable that is already defined in the CI/CD settings or `.gitlab-ci.yml` file,
 the [variable is overridden](../variables/_index.md#use-pipeline-variables) with the new value.
-Any variables overridden by using this process are [expanded](../variables/_index.md#prevent-cicd-variable-expansion)
+Any variables overridden by using this process are [expanded](../variables/_index.md#allow-cicd-variable-expansion)
 and not [masked](../variables/_index.md#mask-a-cicd-variable).
 
 #### Retry a manual job with updated variables
diff --git a/doc/ci/pipelines/_index.md b/doc/ci/pipelines/_index.md
index 20fc3b86786b5d..6a1c0656748363 100644
--- a/doc/ci/pipelines/_index.md
+++ b/doc/ci/pipelines/_index.md
@@ -170,7 +170,7 @@ that have a `description` defined in the `.gitlab-ci.yml` file. The description
 below the variable.
 
 You can change the prefilled value, which [overrides the value](../variables/_index.md#use-pipeline-variables) for that single pipeline run.
-Any variables overridden by using this process are [expanded](../variables/_index.md#prevent-cicd-variable-expansion)
+Any variables overridden by using this process are [expanded](../variables/_index.md#allow-cicd-variable-expansion)
 and not [masked](../variables/_index.md#mask-a-cicd-variable).
 If you do not define a `value` for the variable in the configuration file, the variable name is still listed,
 but the value field is blank.
diff --git a/doc/ci/variables/_index.md b/doc/ci/variables/_index.md
index 046a0a0af5230f..4954ef41421115 100644
--- a/doc/ci/variables/_index.md
+++ b/doc/ci/variables/_index.md
@@ -292,7 +292,7 @@ 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.
+1. Recommended. Clear the [**Expand variable reference**](#allow-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.
@@ -416,17 +416,18 @@ job:
     - mytool --url-file="site-url.txt"
 ```
 
-## Prevent CI/CD variable expansion
+## Allow 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.
+- Changed to disabled by default in GitLab 18.6.
 
 {{< /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.
+CI/CD variables are not expanded by default. To treat a variable value with a `$` character
+as a reference to another variable, enable variable expansion.
 
 {{< alert type="note" >}}
 
@@ -439,12 +440,12 @@ 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).
 
-To disable variable expansion for the variable:
+To enable 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 reference** checkbox.
+1. Select the **Expand variable reference** checkbox.
 1. Select **Update variable**.
 
 ## CI/CD variable precedence
diff --git a/spec/frontend/ci/ci_variable_list/components/ci_variable_drawer_spec.js b/spec/frontend/ci/ci_variable_list/components/ci_variable_drawer_spec.js
index 93cbd2d2b2310a..4d78fe89c8a82d 100644
--- a/spec/frontend/ci/ci_variable_list/components/ci_variable_drawer_spec.js
+++ b/spec/frontend/ci/ci_variable_list/components/ci_variable_drawer_spec.js
@@ -789,7 +789,7 @@ describe('CI Variable Drawer', () => {
               masked: true,
               hidden: false,
               protected: false,
-              raw: false, // opposite of expanded
+              raw: true, // opposite of expanded
               value: 'NEW_VALUE',
               variableType: 'ENV_VAR',
             },
-- 
GitLab


From 390967853114dd8e82db83f8ca66084484a71def Mon Sep 17 00:00:00 2001
From: Anna Vovchenko <avovchenko@gitlab.com>
Date: Thu, 16 Oct 2025 23:33:04 +0300
Subject: [PATCH 4/8] Fix tests for CI variable drawer

Update tests to reflect the change of the `raw` field's default value.
---
 .../components/ci_variable_drawer_spec.js     | 79 +++++++++++--------
 1 file changed, 47 insertions(+), 32 deletions(-)

diff --git a/spec/frontend/ci/ci_variable_list/components/ci_variable_drawer_spec.js b/spec/frontend/ci/ci_variable_list/components/ci_variable_drawer_spec.js
index 4d78fe89c8a82d..53f360b3d40ee4 100644
--- a/spec/frontend/ci/ci_variable_list/components/ci_variable_drawer_spec.js
+++ b/spec/frontend/ci/ci_variable_list/components/ci_variable_drawer_spec.js
@@ -59,6 +59,7 @@ describe('CI Variable Drawer', () => {
     hideEnvironmentScope: false,
     selectedVariable: {},
     mode: ADD_VARIABLE_ACTION,
+    raw: true,
   };
 
   const defaultProvide = {
@@ -480,24 +481,24 @@ describe('CI Variable Drawer', () => {
         createComponent();
       });
 
-      it('is true by default when adding a variable', () => {
-        expect(findExpandedCheckbox().attributes('checked')).toBeDefined();
+      it('is false by default when adding a variable', () => {
+        expect(findExpandedCheckbox().attributes('checked')).toBeUndefined();
       });
 
       it('inherits value of selected variable when editing', () => {
         createComponent({
           props: {
-            selectedVariable: mockProjectVariableFileType,
+            selectedVariable: mockProjectVariable,
             mode: EDIT_VARIABLE_ACTION,
           },
         });
 
-        expect(findExpandedCheckbox().attributes('checked')).toBeUndefined();
+        expect(findExpandedCheckbox().attributes('checked')).toBe('true');
       });
 
       it("sets the variable's raw value", async () => {
         findKeyField().vm.$emit('input', 'NEW_VARIABLE');
-        findExpandedCheckbox().vm.$emit('change');
+        findExpandedCheckbox().vm.$emit('change', true);
         findConfirmBtn().vm.$emit('click');
 
         await nextTick();
@@ -507,20 +508,23 @@ describe('CI Variable Drawer', () => {
       });
 
       it('shows help text when variable is not expanded (will be evaluated as raw)', async () => {
-        expect(findExpandedCheckbox().attributes('checked')).toBeDefined();
-        expect(findDrawer().text()).not.toContain(
-          'Variable value will be evaluated as raw string.',
-        );
+        expect(findExpandedCheckbox().attributes('checked')).toBeUndefined();
+        expect(findDrawer().text()).toContain('Variable value will be evaluated as raw string.');
 
-        findExpandedCheckbox().vm.$emit('change');
+        findExpandedCheckbox().vm.$emit('change', true);
 
         await nextTick();
 
-        expect(findExpandedCheckbox().attributes('checked')).toBeUndefined();
-        expect(findDrawer().text()).toContain('Variable value will be evaluated as raw string.');
+        expect(findExpandedCheckbox().attributes('checked')).toBeDefined();
+        expect(findDrawer().text()).not.toContain(
+          'Variable value will be evaluated as raw string.',
+        );
       });
 
       it('shows help text when variable is expanded and contains the $ character', async () => {
+        findExpandedCheckbox().vm.$emit('change', true);
+        await nextTick();
+
         expect(findDrawer().text()).not.toContain(
           'Unselect "Expand variable reference" if you want to use the variable value as a raw string.',
         );
@@ -609,22 +613,29 @@ describe('CI Variable Drawer', () => {
       };
 
       describe.each`
-        value                                                | canSubmit | trackingErrorProperty | validationIssueKey
-        ${'secretValue'}                                     | ${true}   | ${null}               | ${''}
-        ${'~v@lid:symbols.'}                                 | ${true}   | ${null}               | ${''}
-        ${invalidValues.short}                               | ${false}  | ${null}               | ${'short'}
-        ${invalidValues.multiLine}                           | ${false}  | ${'\n'}               | ${'multiLine'}
-        ${'dollar$ign'}                                      | ${false}  | ${'$'}                | ${'unsupportedDollarChar'}
-        ${invalidValues.unsupportedChar}                     | ${false}  | ${'|'}                | ${'unsupportedChar'}
-        ${invalidValues.twoUnsupportedChars}                 | ${false}  | ${'|!'}               | ${'twoUnsupportedChars'}
-        ${invalidValues.threeUnsupportedChars}               | ${false}  | ${'%|!'}              | ${'threeUnsupportedChars'}
-        ${invalidValues.shortAndMultiLine}                   | ${false}  | ${'\n'}               | ${'shortAndMultiLine'}
-        ${invalidValues.shortAndUnsupportedChar}             | ${false}  | ${'!'}                | ${'shortAndUnsupportedChar'}
-        ${invalidValues.shortAndMultiLineAndUnsupportedChar} | ${false}  | ${'\n!'}              | ${'shortAndMultiLineAndUnsupportedChar'}
-        ${invalidValues.multiLineAndUnsupportedChar}         | ${false}  | ${'\n!'}              | ${'multiLineAndUnsupportedChar'}
+        value                                                | canSubmit | expanded | trackingErrorProperty | validationIssueKey
+        ${'secretValue'}                                     | ${true}   | ${false} | ${null}               | ${''}
+        ${'~v@lid:symbols.'}                                 | ${true}   | ${false} | ${null}               | ${''}
+        ${'dollar$ign'}                                      | ${true}   | ${false} | ${null}               | ${''}
+        ${'dollar$ign'}                                      | ${false}  | ${true}  | ${'$'}                | ${'unsupportedDollarChar'}
+        ${invalidValues.short}                               | ${false}  | ${false} | ${null}               | ${'short'}
+        ${invalidValues.multiLine}                           | ${false}  | ${false} | ${'\n'}               | ${'multiLine'}
+        ${invalidValues.unsupportedChar}                     | ${true}   | ${false} | ${null}               | ${''}
+        ${invalidValues.unsupportedChar}                     | ${false}  | ${true}  | ${'|'}                | ${'unsupportedChar'}
+        ${invalidValues.twoUnsupportedChars}                 | ${true}   | ${false} | ${null}               | ${''}
+        ${invalidValues.twoUnsupportedChars}                 | ${false}  | ${true}  | ${'|!'}               | ${'twoUnsupportedChars'}
+        ${invalidValues.threeUnsupportedChars}               | ${true}   | ${false} | ${null}               | ${''}
+        ${invalidValues.threeUnsupportedChars}               | ${false}  | ${true}  | ${'%|!'}              | ${'threeUnsupportedChars'}
+        ${invalidValues.shortAndMultiLine}                   | ${false}  | ${false} | ${'\n'}               | ${'shortAndMultiLine'}
+        ${invalidValues.shortAndUnsupportedChar}             | ${false}  | ${false} | ${null}               | ${'short'}
+        ${invalidValues.shortAndUnsupportedChar}             | ${false}  | ${true}  | ${'!'}                | ${'shortAndUnsupportedChar'}
+        ${invalidValues.shortAndMultiLineAndUnsupportedChar} | ${false}  | ${false} | ${'\n'}               | ${'shortAndMultiLine'}
+        ${invalidValues.shortAndMultiLineAndUnsupportedChar} | ${false}  | ${true}  | ${'\n'}               | ${'shortAndMultiLineAndUnsupportedChar'}
+        ${invalidValues.multiLineAndUnsupportedChar}         | ${false}  | ${false} | ${'\n'}               | ${'multiLine'}
+        ${invalidValues.multiLineAndUnsupportedChar}         | ${false}  | ${true}  | ${'\n'}               | ${'multiLineAndUnsupportedChar'}
       `(
         'masking requirements',
-        ({ value, canSubmit, trackingErrorProperty, validationIssueKey }) => {
+        ({ value, canSubmit, expanded, trackingErrorProperty, validationIssueKey }) => {
           beforeEach(() => {
             createComponent({ mountFn: mountExtended });
 
@@ -632,9 +643,11 @@ describe('CI Variable Drawer', () => {
             findKeyField().vm.$emit('input', 'NEW_VARIABLE');
             findValueField().vm.$emit('input', value);
             findVisibilityRadioGroup().vm.$emit('change', VISIBILITY_MASKED);
+
+            findExpandedCheckbox().setChecked(expanded);
           });
 
-          itif(canSubmit)(`can submit when value is ${value}`, () => {
+          itif(canSubmit)(`can submit when value is ${value} and expanded=${expanded}`, () => {
             /* eslint-disable jest/no-standalone-expect */
             expect(findInvalidMaskedValueErrorList().text()).toBe('');
             expect(findConfirmBtn().attributes('disabled')).toBeUndefined();
@@ -642,7 +655,7 @@ describe('CI Variable Drawer', () => {
           });
 
           itif(!canSubmit)(
-            `shows validation errors and disables submit button when value is ${value}`,
+            `shows validation errors and disables submit button when value is ${value} and expanded=${expanded}`,
             () => {
               const validationIssueText = maskedValidationIssuesText[validationIssueKey] || '';
               const errorText = findInvalidMaskedValueErrorsWrapper().text();
@@ -655,7 +668,7 @@ describe('CI Variable Drawer', () => {
           );
 
           itif(trackingErrorProperty)(
-            `sends the correct variable validation tracking event when value is ${value}`,
+            `sends the correct variable validation tracking event when value is ${value} and expanded=${expanded}`,
             () => {
               /* eslint-disable jest/no-standalone-expect */
               expect(trackingSpy).toHaveBeenCalledTimes(1);
@@ -668,7 +681,7 @@ describe('CI Variable Drawer', () => {
           );
 
           itif(!trackingErrorProperty)(
-            `does not send the the correct variable validation tracking event when value is ${value}`,
+            `does not send the the correct variable validation tracking event when value is ${value} and expanded=${expanded}`,
             () => {
               // eslint-disable-next-line jest/no-standalone-expect
               expect(trackingSpy).toHaveBeenCalledTimes(0);
@@ -681,6 +694,7 @@ describe('CI Variable Drawer', () => {
         trackingSpy = mockTracking(undefined, wrapper.element, jest.spyOn);
         findKeyField().vm.$emit('input', 'NEW_VARIABLE');
         findVisibilityRadioGroup().vm.$emit('change', VISIBILITY_MASKED);
+        findExpandedCheckbox().vm.$emit('change', true);
 
         await nextTick();
 
@@ -705,6 +719,7 @@ describe('CI Variable Drawer', () => {
         findKeyField().vm.$emit('input', 'NEW_VARIABLE');
         findValueField().vm.$emit('input', '~v@lid:symbols.');
         findVisibilityRadioGroup().vm.$emit('change', VISIBILITY_HIDDEN);
+        findExpandedCheckbox().setChecked(true);
 
         await nextTick();
 
@@ -773,7 +788,7 @@ describe('CI Variable Drawer', () => {
         findDescriptionField().vm.$emit('input', 'NEW_DESCRIPTION');
         findKeyField().vm.$emit('input', 'NEW_VARIABLE');
         findProtectedCheckbox().vm.$emit('input', false);
-        findExpandedCheckbox().vm.$emit('input', true);
+        findExpandedCheckbox().vm.$emit('change', true);
         findVisibilityRadioGroup().vm.$emit('change', VISIBILITY_MASKED);
         findValueField().vm.$emit('input', 'NEW_VALUE');
         findConfirmBtn().vm.$emit('click');
@@ -789,7 +804,7 @@ describe('CI Variable Drawer', () => {
               masked: true,
               hidden: false,
               protected: false,
-              raw: true, // opposite of expanded
+              raw: false, // opposite of expanded
               value: 'NEW_VALUE',
               variableType: 'ENV_VAR',
             },
-- 
GitLab


From c0a34de18b36acd4eaf5ab00a42988db7b4ad26f Mon Sep 17 00:00:00 2001
From: Anna Vovchenko <avovchenko@gitlab.com>
Date: Fri, 17 Oct 2025 00:11:42 +0300
Subject: [PATCH 5/8] Update the docs

Remove unused reference. Update to the new anchor.
---
 app/assets/javascripts/ci/ci_variable_list/index.js      | 2 --
 app/views/ci/variables/_index.html.haml                  | 1 -
 doc/api/group_level_variables.md                         | 4 ++--
 doc/api/project_level_variables.md                       | 4 ++--
 doc/ci/pipelines/downstream_pipelines_troubleshooting.md | 2 +-
 5 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/app/assets/javascripts/ci/ci_variable_list/index.js b/app/assets/javascripts/ci/ci_variable_list/index.js
index ad3e81423c9824..df2c9aa22d153d 100644
--- a/app/assets/javascripts/ci/ci_variable_list/index.js
+++ b/app/assets/javascripts/ci/ci_variable_list/index.js
@@ -10,7 +10,6 @@ import { generateCacheConfig, resolvers } from './graphql/settings';
 
 const mountCiVariableListApp = (containerEl) => {
   const {
-    containsVariableReferenceLink,
     endpoint,
     groupId,
     groupPath,
@@ -52,7 +51,6 @@ const mountCiVariableListApp = (containerEl) => {
     el: containerEl,
     apolloProvider,
     provide: {
-      containsVariableReferenceLink,
       endpoint,
       groupId,
       groupPath,
diff --git a/app/views/ci/variables/_index.html.haml b/app/views/ci/variables/_index.html.haml
index e2a074df051d47..dd032d9d49dd4a 100644
--- a/app/views/ci/variables/_index.html.haml
+++ b/app/views/ci/variables/_index.html.haml
@@ -27,7 +27,6 @@
   maskable_raw_regex: ci_variable_maskable_raw_regex,
   maskable_regex: ci_variable_maskable_regex,
   protected_by_default: ci_variable_protected_by_default?.to_s,
-  contains_variable_reference_link: help_page_path('ci/variables/_index.md', anchor: 'prevent-cicd-variable-expansion'),
   masked_environment_variables_link: help_page_path('ci/variables/_index.md', anchor: 'mask-a-cicd-variable') } }
 
 - if !@group && @project.group
diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md
index a565eabcd5ceb3..d4f76a9c1514c7 100644
--- a/doc/api/group_level_variables.md
+++ b/doc/api/group_level_variables.md
@@ -125,7 +125,7 @@ POST /groups/:id/variables
 | `masked`                              | boolean        | No       | Whether the variable is masked. |
 | `masked_and_hidden`                   | boolean        | No       | Whether the variable is masked and hidden. Default: `false` |
 | `protected`                           | boolean        | No       | Whether the variable is protected. |
-| `raw`                                 | boolean        | No       | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/_index.md#prevent-cicd-variable-expansion). |
+| `raw`                                 | boolean        | No       | Whether the variable is treated as a raw string. Default: `true`. When `false`, variables in the value are [expanded](../ci/variables/_index.md#allow-cicd-variable-expansion). |
 | `variable_type`                       | string         | No       | The type of a variable. Available types are: `env_var` (default) and `file`. |
 
 ```shell
@@ -175,7 +175,7 @@ PUT /groups/:id/variables/:key
 | `filter`                              | hash           | No       | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). |
 | `masked`                              | boolean        | No       | Whether the variable is masked |
 | `protected`                           | boolean        | No       | Whether the variable is protected |
-| `raw`                                 | boolean        | No       | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/_index.md#prevent-cicd-variable-expansion). |
+| `raw`                                 | boolean        | No       | Whether the variable is treated as a raw string. Default: `true`. When `false`, variables in the value are [expanded](../ci/variables/_index.md#allow-cicd-variable-expansion). |
 | `variable_type`                       | string         | No       | The type of a variable. Available types are: `env_var` (default) and `file` |
 
 ```shell
diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md
index b98dffdabfd0bd..83595efa6ee624 100644
--- a/doc/api/project_level_variables.md
+++ b/doc/api/project_level_variables.md
@@ -125,7 +125,7 @@ POST /projects/:id/variables
 | `masked`            | boolean        | No       | Whether the variable is masked. Default: `false` |
 | `masked_and_hidden` | boolean        | No       | Whether the variable is masked and hidden. Default: `false` |
 | `protected`         | boolean        | No       | Whether the variable is protected. Default: `false` |
-| `raw`               | boolean        | No       | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/_index.md#prevent-cicd-variable-expansion). |
+| `raw`               | boolean        | No       | Whether the variable is treated as a raw string. Default: `true`. When `false`, variables in the value are [expanded](../ci/variables/_index.md#allow-cicd-variable-expansion). |
 | `variable_type`     | string         | No       | The type of a variable. Available types are: `env_var` (default) and `file` |
 
 Example request:
@@ -170,7 +170,7 @@ PUT /projects/:id/variables/:key
 | `filter`            | hash           | No       | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). |
 | `masked`            | boolean        | No       | Whether the variable is masked |
 | `protected`         | boolean        | No       | Whether the variable is protected |
-| `raw`               | boolean        | No       | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/_index.md#prevent-cicd-variable-expansion). |
+| `raw`               | boolean        | No       | Whether the variable is treated as a raw string. Default: `true`. When `false`, variables in the value are [expanded](../ci/variables/_index.md#allow-cicd-variable-expansion). |
 | `variable_type`     | string         | No       | The type of a variable. Available types are: `env_var` (default) and `file` |
 
 Example request:
diff --git a/doc/ci/pipelines/downstream_pipelines_troubleshooting.md b/doc/ci/pipelines/downstream_pipelines_troubleshooting.md
index 5968629c496109..a925c128daa63d 100644
--- a/doc/ci/pipelines/downstream_pipelines_troubleshooting.md
+++ b/doc/ci/pipelines/downstream_pipelines_troubleshooting.md
@@ -38,7 +38,7 @@ You cannot use [`$$` to escape the `$` character in a CI/CD variable](../variabl
 when [passing a CI/CD variable to a downstream pipeline](downstream_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline).
 The downstream pipeline still treats the `$` as the start of a variable reference.
 
-You can [Prevent CI/CD variable expansion](../variables/_index.md#prevent-cicd-variable-expansion) when configuring
+You can [Prevent CI/CD variable expansion](../variables/_index.md#allow-cicd-variable-expansion) when configuring
 a variable in the UI, or use the [`variables:expand` keyword](../yaml/_index.md#variablesexpand) to
 set a variable value to not be expanded. This variable can then be passed to the downstream pipeline
 without the `$` being interpreted as a variable reference.
-- 
GitLab


From 3d36255ca80c4c8d3e7d08ef178ebe89444c850b Mon Sep 17 00:00:00 2001
From: Anna Vovchenko <avovchenko@gitlab.com>
Date: Fri, 17 Oct 2025 11:41:26 +0300
Subject: [PATCH 6/8] Fix ruby test to reflect the changes

---
 .../features/variable_list_drawer_shared_examples.rb       | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/spec/support/shared_examples/features/variable_list_drawer_shared_examples.rb b/spec/support/shared_examples/features/variable_list_drawer_shared_examples.rb
index e07d4d8d487c7c..1d66c17fd66825 100644
--- a/spec/support/shared_examples/features/variable_list_drawer_shared_examples.rb
+++ b/spec/support/shared_examples/features/variable_list_drawer_shared_examples.rb
@@ -50,10 +50,10 @@
     end
   end
 
-  it 'defaults to masked, expanded' do
+  it 'defaults to masked, not expanded' do
     open_drawer
 
-    fill_variable('NEW_KEY')
+    fill_variable('NEW_KEY', 'NEW_VALUE')
     click_add_variable
 
     wait_for_requests
@@ -62,7 +62,7 @@
       key_column = first(".js-ci-variable-row:nth-child(1) td[data-label='#{s_('CiVariables|Key')}']")
 
       expect(key_column).to have_content(s_('CiVariables|Masked'))
-      expect(key_column).to have_content(s_('CiVariables|Expanded'))
+      expect(key_column).not_to have_content(s_('CiVariables|Expanded'))
     end
   end
 
@@ -196,6 +196,7 @@
     open_drawer
 
     set_masked
+    toggle_expanded
     fill_variable('EMPTY_MASK_KEY', '???')
 
     expect(page).to have_content('The value cannot contain the following characters: ?.')
-- 
GitLab


From 36743af1684570b6649ee9b369473eb21565aa9a Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Tue, 21 Oct 2025 00:14:47 +0900
Subject: [PATCH 7/8] Clarify note about combined variable settings

---
 doc/ci/variables/_index.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/ci/variables/_index.md b/doc/ci/variables/_index.md
index 4954ef41421115..a7b615e8909513 100644
--- a/doc/ci/variables/_index.md
+++ b/doc/ci/variables/_index.md
@@ -431,8 +431,9 @@ as a reference to another variable, enable variable expansion.
 
 {{< 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.
+Do not [mask](#mask-a-cicd-variable) a variable value if you want to use variable expansion.
+If both masking and variable expansion are combined, character limitations prevent
+the use of the `$` to reference other variables.
 
 {{< /alert >}}
 
-- 
GitLab


From c88fe919b1aba19ce812a2095a38fc9812e9d297 Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Wed, 22 Oct 2025 16:03:44 +0900
Subject: [PATCH 8/8] Update details about defaults for yaml variables

---
 doc/ci/variables/_index.md | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/doc/ci/variables/_index.md b/doc/ci/variables/_index.md
index a7b615e8909513..3418d2c2ba8c0c 100644
--- a/doc/ci/variables/_index.md
+++ b/doc/ci/variables/_index.md
@@ -421,21 +421,15 @@ job:
 {{< history >}}
 
 - **Expand variable** option [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/410414) to **Expand variable reference** in GitLab 16.3.
-- Changed to disabled by default in GitLab 18.6.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/209144) to disabled by default in GitLab 18.6.
 
 {{< /history >}}
 
-Expanded variables treat values with the `$` character as a reference to another variable.
-CI/CD variables are not expanded by default. To treat a variable value with a `$` character
-as a reference to another variable, enable variable expansion.
+You can set a variable to treat values with the `$` character as a reference to another variable.
+When the pipeline runs, the reference expands to use the value of the referenced variable.
 
-{{< alert type="note" >}}
-
-Do not [mask](#mask-a-cicd-variable) a variable value if you want to use variable expansion.
-If both masking and variable expansion are combined, character limitations prevent
-the use of the `$` to reference other variables.
-
-{{< /alert >}}
+CI/CD variables defined in the UI are not expanded by default. For CI/CD variables defined in
+the `.gitlab-ci.yml` file, control variable expansion with the [`variables:expand` keyword](../yaml/_index.md#variablesexpand).
 
 Prerequisites:
 
@@ -449,6 +443,14 @@ To enable variable expansion for the variable:
 1. Select the **Expand variable reference** checkbox.
 1. Select **Update variable**.
 
+{{< alert type="note" >}}
+
+Do not [mask](#mask-a-cicd-variable) a variable value if you want to use variable expansion.
+If both masking and variable expansion are combined, character limitations prevent
+the use of the `$` to reference other variables.
+
+{{< /alert >}}
+
 ## CI/CD variable precedence
 
 {{< history >}}
-- 
GitLab