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`:
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),
- [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).
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)
environment variables might need to be surrounded by quotes to expand properly:
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#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)
the variable can be available for.
To learn more about scoping environments, see [Scoping environments with specs](../environments/index.md#scoping-environments-with-specs).
To learn more about ensuring CI/CD variables are only exposed in pipelines running from protected
branches or tags, see [Protect a CI/CD Variable](#protect-a-cicd-variable).
## Deployment variables
Integrations that are responsible for deployment configuration can define their own
variables that are set in the build environment. These variables are only defined
for [deployment jobs](../environments/index.md).
For example, the [Kubernetes integration](../../user/project/clusters/deploy_to_cluster.md#deployment-variables)
defines deployment variables that you can use with the integration.
The [documentation for each integration](../../user/project/integrations/overview.md)
explains if the integration has any deployment variables available.
## Auto DevOps environment variables
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/49056) in GitLab 11.7.
You can configure [Auto DevOps](../../topics/autodevops/index.md) 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](../../topics/autodevops/customize.md#application-secret-variables)
with `K8S_SECRET_`.
CI/CD variables with multi-line values are not supported.
## Debug logging
> Introduced in GitLab Runner 1.7.
WARNING:
Debug logging can be a serious security risk. The output contains the content of
all variables and other secrets available to the job. The output is uploaded to the
GitLab server and visible in job logs.
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](../../user/permissions.md#project-features)
can view job logs. You should also [delete job logs](../jobs/index.md#view-jobs-in-a-pipeline)
with debug output before you make logs public again.
### Enable Debug logging
To enable debug logging (tracing), set the `CI_DEBUG_TRACE` variable to `true`:
> - [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.