<commit_before>---
table_display_block: true
---

# GitLab CI/CD environment variables

After a brief overview over the use of environment
variables, this document teaches you how to use GitLab CI/CD's
variables, presents the full reference for predefined variables,
and dives into more advanced applications.

## Overview

An environment variable is a dynamic-named value that can
affect the way running processes will behave on an operating
system.

They are part of the environment in which a process runs.
For example, a running process can query the value of the
`TEMP` environment variable to discover a suitable location
to store temporary files, or to define a `URL` for a database
that can be reused in different scripts.

Variables are useful for customizing your jobs in GitLab
CI/CD's pipelines. Using variables means no hardcoded values.

### Predefined environment variables

GitLab CI/CD has a default set of
[predefined variables](predefined_variables.md)
which can be used without any specification needed.
You can call issues numbers, user names, branch names,
pipeline and commit IDs, and much more.

Predefined environment variables are the ones that GitLab
provides out of the box for the local environment of the Runner.

GitLab reads the .gitlab-ci.yml file, sends the information
to the Runner (which runs the script commands), under which
the variables are exposed.

For example, two jobs under the same pipeline can share the same
`CI_PIPELINE_ID` variable, but each one has its own `CI_JOB_ID`
variable.

### Custom environment variables

When your use case requires a specific variable, you can
[set them up easily from the UI](#creating-a-custom-environment-variable)
or directly in the `.gitlab-ci.yml` file and reuse them as you wish.

That can be very powerful as it can be used for scripting without
the need to specify the value itself.

## Getting started

To get started with environment variables in the scope of GitLab
CI/CD, let's go over a few examples.

### Using predefined environment variables

To get started, choose one of the existing
[predefined variables](predefined_variables.md)
to be output by the Runner. For example, let's say that you want
a given job you're running through your script to output the
stage that job is running for. In your `.gitlab-ci.yml` file,
call the variable from your script according to the [syntaxes](#syntax-of-environment-variables-in-job-scripts) available. To
output the job stage, use the predefined variable `CI_JOB_STAGE`:

```yaml
test_variable:
  stage: test
  script:
    - echo $CI_JOB_STAGE
```

For this case, the Runner will output the `stage` for the
job `test_variable`, which is `test`:

![Output `$CI_JOB_STAGE`](img/ci_job_stage_output_example.png)

As another example, let's say you're using your own GitLab
instance you want to know what domain your GitLab Pages are
served under. You can easily call it with the predefined
variable `$CI_PAGES_DOMAIN` in your script:

```yaml
pages:
  script:
    - ...
    - echo $CI_PAGES_DOMAIN
```

For GitLab.com users, the output will be `gitlab.io`. For your
private instance, the output will be whatever your sysadmin has
defined.

### Creating a custom environment variable

Assume you have something you want to repeat through your scripts
in GitLab CI/CD's configuration file. To keep this example simple,
let's say you want to output `HELLO WORLD` for a `TEST` variable.

You can either set the variable directly in the `.gitlab-ci.yml`
file or through the UI.

#### Via [`.gitlab-ci.yml`](../yaml/README.md#variables)

```yaml
variables:
  TEST: "HELLO WORLD"
```

For a deeper look into them, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined-variables).

#### Via the UI

From the UI, navigate to your project's **Settings > CI/CD** and
expand **Environment variables**. Create a new variable by naming
it in the field **Input variable key**, and define its value in the
**Input variable value** field:

![CI/CD settings - new variable](img/new_custom_variable_example.png)

Once you've set the variables, call them from the `.gitlab-ci.yml` file:

```yaml
test_variable:
  stage: test
  script:
    - echo $CI_JOB_STAGE # calls a predefined variable
    - echo $TEST # calls a custom variable
```

The output will be:

![Output custom variable](img/custom_variable_output.png)

### Masked Variables

By default, variables will be created as masked variables.
This means that the value of the variable will be hidden in job logs,
though it must match certain requirements to do so:

- The value must be a single line.
- The value must not have escape characters.
- The value must not use variables.
- The value must not have any whitespace.
- The value must be at least 8 characters long.

If the value does not meet the requirements above, then the CI variable will fail to save.
In order to save, either alter the value to meet the masking requirements
or disable `Masked` for the variable.

### Syntax of environment variables in job scripts

All variables are set as environment variables in the build environment, and
they are accessible with normal methods that are used to access such variables.
In most cases `bash` or `sh` is used to execute the job script.

To access environment variables, use the syntax for your Runner's [shell][shellexecutors].

| Shell                | Usage           |
|----------------------|-----------------|
| bash/sh              | `$variable`     |
| windows batch        | `%variable%`    |
| PowerShell           | `$env:variable` |

To access environment variables in bash, prefix the variable name with (`$`):
<commit_msg>Docs: fixes grammar/typo<commit_after>---
table_display_block: true
---

# GitLab CI/CD environment variables

After a brief overview over the use of environment
variables, this document teaches you how to use GitLab CI/CD's
variables, presents the full reference for predefined variables,
and dives into more advanced applications.

## Overview

An environment variable is a dynamic-named value that can
affect the way running processes will behave on an operating
system.

They are part of the environment in which a process runs.
For example, a running process can query the value of the
`TEMP` environment variable to discover a suitable location
to store temporary files, or to define a `URL` for a database
that can be reused in different scripts.

Variables are useful for customizing your jobs in GitLab
CI/CD's pipelines. Using variables means no hardcoded values.

### Predefined environment variables

GitLab CI/CD has a default set of
[predefined variables](predefined_variables.md)
which can be used without any specification needed.
You can call issues numbers, user names, branch names,
pipeline and commit IDs, and much more.

Predefined environment variables are the ones that GitLab
provides out of the box for the local environment of the Runner.

GitLab reads the .gitlab-ci.yml file, sends the information
to the Runner (which runs the script commands), under which
the variables are exposed.

For example, two jobs under the same pipeline can share the same
`CI_PIPELINE_ID` variable, but each one has its own `CI_JOB_ID`
variable.

### Custom environment variables

When your use case requires a specific variable, you can
[set them up easily from the UI](#creating-a-custom-environment-variable)
or directly in the `.gitlab-ci.yml` file and reuse them as you wish.

That can be very powerful as it can be used for scripting without
the need to specify the value itself.

## Getting started

To get started with environment variables in the scope of GitLab
CI/CD, let's go over a few examples.

### Using predefined environment variables

To get started, choose one of the existing
[predefined variables](predefined_variables.md)
to be output by the Runner. For example, let's say that you want
a given job you're running through your script to output the
stage that job is running for. In your `.gitlab-ci.yml` file,
call the variable from your script according to the [syntaxes](#syntax-of-environment-variables-in-job-scripts) available. To
output the job stage, use the predefined variable `CI_JOB_STAGE`:

```yaml
test_variable:
  stage: test
  script:
    - echo $CI_JOB_STAGE
```

For this case, the Runner will output the `stage` for the
job `test_variable`, which is `test`:

![Output `$CI_JOB_STAGE`](img/ci_job_stage_output_example.png)

As another example, let's say you're using your own GitLab
instance you want to know what domain your GitLab Pages are
served under. You can easily call it with the predefined
variable `$CI_PAGES_DOMAIN` in your script:

```yaml
pages:
  script:
    - ...
    - echo $CI_PAGES_DOMAIN
```

For GitLab.com users, the output will be `gitlab.io`. For your
private instance, the output will be whatever your sysadmin has
defined.

### Creating a custom environment variable

Assume you have something you want to repeat through your scripts
in GitLab CI/CD's configuration file. To keep this example simple,
let's say you want to output `HELLO WORLD` for a `TEST` variable.

You can either set the variable directly in the `.gitlab-ci.yml`
file or through the UI.

#### Via [`.gitlab-ci.yml`](../yaml/README.md#variables)

```yaml
variables:
  TEST: "HELLO WORLD"
```

For a deeper look into them, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined-variables).

#### Via the UI

From the UI, navigate to your project's **Settings > CI/CD** and
expand **Environment variables**. Create a new variable by naming
it in the field **Input variable key**, and define its value in the
**Input variable value** field:

![CI/CD settings - new variable](img/new_custom_variable_example.png)

Once you've set the variables, call them from the `.gitlab-ci.yml` file:

```yaml
test_variable:
  stage: test
  script:
    - echo $CI_JOB_STAGE # calls a predefined variable
    - echo $TEST # calls a custom variable
```

The output will be:

![Output custom variable](img/custom_variable_output.png)

### Masked Variables

By default, variables will be created as masked variables.
This means that the value of the variable will be hidden in job logs,
though it must match certain requirements to do so:

- The value must be in a single line.
- The value must not have escape characters.
- The value must not use variables.
- The value must not have any whitespace.
- The value must be at least 8 characters long.

If the value does not meet the requirements above, then the CI variable will fail to save.
In order to save, either alter the value to meet the masking requirements
or disable `Masked` for the variable.

### Syntax of environment variables in job scripts

All variables are set as environment variables in the build environment, and
they are accessible with normal methods that are used to access such variables.
In most cases `bash` or `sh` is used to execute the job script.

To access environment variables, use the syntax for your Runner's [shell][shellexecutors].

| Shell                | Usage           |
|----------------------|-----------------|
| bash/sh              | `$variable`     |
| windows batch        | `%variable%`    |
| PowerShell           | `$env:variable` |

To access environment variables in bash, prefix the variable name with (`$`):

{'fraction_non_alphanumeric': 0.07647267565649397, 'fraction_numerical': 0.000177430801987225, 'mean_word_length': 4.003550821127385, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3277500', 'n_tokens_mistral': 3155, 'n_tokens_neox': 2984, 'n_words': 1573}