2019-03-02 22:35:43 +05:30
|
|
|
---
|
|
|
|
table_display_block: true
|
|
|
|
---
|
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
# GitLab CI/CD environment variables
|
|
|
|
{: #variables}
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
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.
|
2019-03-02 22:35:43 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
## Overview
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
An environment variable is a dynamic-named value that can
|
|
|
|
affect the way running processes will behave on an operating
|
|
|
|
system.
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
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.
|
2019-03-02 22:35:43 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
Variables are useful for customizing your jobs in GitLab
|
|
|
|
CI/CD's pipelines. Using variables means no hardcoded values.
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
### Predefined environment variables
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
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.
|
2019-03-02 22:35:43 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
Predefined environment variables are the ones that GitLab
|
|
|
|
provides out of the box for the local environment of the Runner.
|
2019-03-02 22:35:43 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
GitLab reads the .gitlab-ci.yml file, sends the information
|
|
|
|
to the Runner (which runs the script commands), under which
|
|
|
|
the variables are exposed.
|
2018-11-08 19:23:39 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
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.
|
2018-11-08 19:23:39 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
### Custom environment variables
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
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.
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
That can be very powerful as it can be used for scripting without
|
|
|
|
the need to specify the value itself.
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
## 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-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
|
|
|
|
{: #syntax-of-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 (`$`):
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
job_name:
|
|
|
|
script:
|
|
|
|
- echo $CI_JOB_ID
|
|
|
|
```
|
|
|
|
|
|
|
|
To access environment variables in **Windows Batch**, surround the variable
|
|
|
|
with (`%`):
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
job_name:
|
|
|
|
script:
|
|
|
|
- echo %CI_JOB_ID%
|
|
|
|
```
|
|
|
|
|
|
|
|
To access environment variables in a **Windows PowerShell** environment, prefix
|
|
|
|
the variable name with (`$env:`):
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
job_name:
|
|
|
|
script:
|
|
|
|
- echo $env:CI_JOB_ID
|
|
|
|
```
|
|
|
|
|
|
|
|
You can also list all environment variables with the `export` command,
|
|
|
|
but be aware that this will also expose the values of all the variables
|
|
|
|
you set, in the job log:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
job_name:
|
|
|
|
script:
|
|
|
|
- export
|
|
|
|
```
|
|
|
|
|
|
|
|
Example values:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
export CI_JOB_ID="50"
|
|
|
|
export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a"
|
|
|
|
export CI_COMMIT_SHORT_SHA="1ecfd275"
|
|
|
|
export CI_COMMIT_REF_NAME="master"
|
|
|
|
export CI_REPOSITORY_URL="https://gitlab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-ce.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="abcde-1234ABCD5678ef"
|
|
|
|
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-ce"
|
|
|
|
export CI_PROJECT_ID="34"
|
|
|
|
export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-ce"
|
|
|
|
export CI_PROJECT_NAME="gitlab-ce"
|
|
|
|
export CI_PROJECT_NAMESPACE="gitlab-org"
|
|
|
|
export CI_PROJECT_PATH="gitlab-org/gitlab-ce"
|
|
|
|
export CI_PROJECT_URL="https://example.com/gitlab-org/gitlab-ce"
|
|
|
|
export CI_REGISTRY="registry.example.com"
|
|
|
|
export CI_REGISTRY_IMAGE="registry.example.com/gitlab-org/gitlab-ce"
|
|
|
|
export CI_RUNNER_ID="10"
|
|
|
|
export CI_RUNNER_DESCRIPTION="my runner"
|
|
|
|
export CI_RUNNER_TAGS="docker, linux"
|
|
|
|
export CI_SERVER="yes"
|
|
|
|
export CI_SERVER_NAME="GitLab"
|
|
|
|
export CI_SERVER_REVISION="70606bf"
|
|
|
|
export CI_SERVER_VERSION="8.9.0"
|
|
|
|
export CI_SERVER_VERSION_MAJOR="8"
|
|
|
|
export CI_SERVER_VERSION_MINOR="9"
|
|
|
|
export CI_SERVER_VERSION_PATCH="0"
|
|
|
|
export GITLAB_USER_ID="42"
|
|
|
|
export GITLAB_USER_EMAIL="user@example.com"
|
|
|
|
export CI_REGISTRY_USER="gitlab-ci-token"
|
|
|
|
export CI_REGISTRY_PASSWORD="longalfanumstring"
|
|
|
|
```
|
|
|
|
|
|
|
|
### `.gitlab-ci.yml` defined variables
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2018-11-20 20:47:30 +05:30
|
|
|
NOTE: **Note:**
|
2019-02-15 15:39:39 +05:30
|
|
|
This feature requires GitLab Runner 0.5.0 or higher and GitLab 7.14 or higher.
|
2017-08-17 22:00:37 +05:30
|
|
|
|
|
|
|
GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in the
|
|
|
|
build environment. The variables are hence saved in the repository, and they
|
2019-03-02 22:35:43 +05:30
|
|
|
are meant to store non-sensitive project configuration. For example, `RAILS_ENV` or
|
2017-08-17 22:00:37 +05:30
|
|
|
`DATABASE_URL`.
|
|
|
|
|
|
|
|
For example, if you set the variable below globally (not inside a job), it will
|
|
|
|
be used in all executed commands and scripts:
|
2015-09-25 12:07:36 +05:30
|
|
|
|
2017-08-17 22:00:37 +05:30
|
|
|
```yaml
|
|
|
|
variables:
|
|
|
|
DATABASE_URL: "postgres://postgres@postgres/my_database"
|
2015-09-25 12:07:36 +05:30
|
|
|
```
|
|
|
|
|
2017-08-17 22:00:37 +05:30
|
|
|
The YAML-defined variables are also set to all created
|
|
|
|
[service containers](../docker/using_docker_images.md), thus allowing to fine
|
|
|
|
tune them.
|
|
|
|
|
|
|
|
Variables can be defined at a global level, but also at a job level. To turn off
|
2017-09-10 17:25:29 +05:30
|
|
|
global defined variables in your job, define an empty hash:
|
2015-09-25 12:07:36 +05:30
|
|
|
|
2017-08-17 22:00:37 +05:30
|
|
|
```yaml
|
|
|
|
job_name:
|
2017-09-10 17:25:29 +05:30
|
|
|
variables: {}
|
2017-08-17 22:00:37 +05:30
|
|
|
```
|
|
|
|
|
|
|
|
You are able to use other variables inside your variable definition (or escape them with `$$`):
|
2015-09-25 12:07:36 +05:30
|
|
|
|
|
|
|
```yaml
|
|
|
|
variables:
|
2017-08-17 22:00:37 +05:30
|
|
|
LS_CMD: 'ls $FLAGS $$TMP_DIR'
|
|
|
|
FLAGS: '-al'
|
|
|
|
script:
|
|
|
|
- 'eval $LS_CMD' # will execute 'ls -al $TMP_DIR'
|
2015-09-25 12:07:36 +05:30
|
|
|
```
|
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
### Group-level environment variables
|
|
|
|
{: #group-level-variables}
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
> Introduced in GitLab 9.4.
|
2018-03-17 18:26:18 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
GitLab CI/CD allows you to define per-project or per-group variables
|
|
|
|
that are set in the pipeline environment. Group-level variables are stored out of
|
2018-03-17 18:26:18 +05:30
|
|
|
the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner
|
2019-05-18 00:54:41 +05:30
|
|
|
making them available during a pipeline run. It's the **recommended method** to
|
2019-03-02 22:35:43 +05:30
|
|
|
use for storing things like passwords, SSH keys, and credentials.
|
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
Group-level variables can be added by:
|
2015-09-25 12:07:36 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
1. Navigating to your group's **Settings > CI/CD** page.
|
2019-03-02 22:35:43 +05:30
|
|
|
1. Inputing variable keys and values in the **Environment variables** section.
|
2019-05-18 00:54:41 +05:30
|
|
|
Any variables of [subgroups](../../user/group/subgroups/index.md) will be inherited recursively.
|
2015-09-25 12:07:36 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
Once you set them, they will be available for all subsequent pipelines.
|
2017-09-10 17:25:29 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
## Priority of environment variables
|
|
|
|
{: #priority-of-variables}
|
|
|
|
|
|
|
|
Variables of different types can take precedence over other
|
|
|
|
variables, depending on where they are defined.
|
2018-03-17 18:26:18 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
The order of precedence for variables is (from highest to lowest):
|
|
|
|
|
|
|
|
1. [Trigger variables](../triggers/README.md#making-use-of-trigger-variables) or [scheduled pipeline variables](../../user/project/pipelines/schedules.md#making-use-of-scheduled-pipeline-variables).
|
|
|
|
1. Project-level [variables](#creating-a-custom-environment-variable) or [protected variables](#protected-variables).
|
|
|
|
1. Group-level [variables](#group-level-variables) or [protected variables](#protected-variables).
|
|
|
|
1. YAML-defined [job-level variables](../yaml/README.md#variables).
|
|
|
|
1. YAML-defined [global variables](../yaml/README.md#variables).
|
|
|
|
1. [Deployment variables](#deployment-variables).
|
|
|
|
1. [Predefined environment variables](predefined_variables.md).
|
|
|
|
|
|
|
|
For example, if you define:
|
|
|
|
|
|
|
|
- `API_TOKEN=secure` as a project variable.
|
|
|
|
- `API_TOKEN=yaml` in your `.gitlab-ci.yml`.
|
|
|
|
|
|
|
|
`API_TOKEN` will take the value `secure` as the project
|
|
|
|
variables take precedence over those defined in `.gitlab-ci.yml`.
|
|
|
|
|
|
|
|
## Unsupported variables
|
|
|
|
|
|
|
|
There are cases where some variables cannot be used in the context of a
|
|
|
|
`.gitlab-ci.yml` definition (for example under `script`). Read more
|
|
|
|
about which variables are [not supported](where_variables_can_be_used.md).
|
2017-09-10 17:25:29 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
## Advanced use
|
|
|
|
|
|
|
|
### Protected environment variables
|
|
|
|
{: #protected-variables}
|
2017-09-10 17:25:29 +05:30
|
|
|
|
2019-02-15 15:39:39 +05:30
|
|
|
> Introduced in GitLab 9.3.
|
2017-09-10 17:25:29 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
Variables can be protected. Whenever a variable is
|
2017-09-10 17:25:29 +05:30
|
|
|
protected, it would only be securely passed to pipelines running on the
|
|
|
|
[protected branches] or [protected tags]. The other pipelines would not get any
|
|
|
|
protected variables.
|
|
|
|
|
|
|
|
Protected variables can be added by going to your project's
|
2018-03-17 18:26:18 +05:30
|
|
|
**Settings > CI/CD**, then finding the section called
|
2018-11-08 19:23:39 +05:30
|
|
|
**Variables**, and check "Protected".
|
2017-09-10 17:25:29 +05:30
|
|
|
|
|
|
|
Once you set them, they will be available for all subsequent pipelines.
|
2016-06-02 11:05:42 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
### Deployment environment variables
|
|
|
|
{: #deployment-variables}
|
2015-09-25 12:07:36 +05:30
|
|
|
|
2019-02-15 15:39:39 +05:30
|
|
|
> Introduced in GitLab 8.15.
|
2016-11-03 12:29:30 +05:30
|
|
|
|
2017-08-17 22:00:37 +05:30
|
|
|
[Project services](../../user/project/integrations/project_services.md) that are
|
|
|
|
responsible for deployment configuration may define their own variables that
|
|
|
|
are set in the build environment. These variables are only defined for
|
|
|
|
[deployment jobs](../environments.md). Please consult the documentation of
|
|
|
|
the project services that you are using to learn which variables they define.
|
|
|
|
|
2018-11-08 19:23:39 +05:30
|
|
|
An example project service that defines deployment variables is the
|
|
|
|
[Kubernetes integration](../../user/project/clusters/index.md#deployment-variables).
|
2017-08-17 22:00:37 +05:30
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
### Auto DevOps environment variables
|
2019-02-15 15:39:39 +05:30
|
|
|
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/49056) in GitLab 11.7.
|
|
|
|
|
|
|
|
You can configure [Auto DevOps](../../topics/autodevops/index.md) to
|
|
|
|
pass CI variables to the running application by prefixing the key of the
|
|
|
|
variable with `K8S_SECRET_`.
|
|
|
|
|
|
|
|
These [prefixed
|
|
|
|
variables](../../topics/autodevops/index.md#application-secret-variables) will
|
|
|
|
then be available as environment variables on the running application
|
|
|
|
container.
|
|
|
|
|
|
|
|
CAUTION: **Caution:**
|
|
|
|
Variables with multiline values are not currently supported due to
|
|
|
|
limitations with the current Auto DevOps scripting environment.
|
|
|
|
|
2019-05-18 00:54:41 +05:30
|
|
|
### Environment variables triggered manually
|
|
|
|
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/44059) in GitLab 10.8.
|
|
|
|
|
|
|
|
[Manually triggered pipelines](../pipelines.md#manually-executing-pipelines) allow you to override the value of a current variable.
|
|
|
|
|
|
|
|
For instance, suppose you added a
|
|
|
|
[custom variable `$TEST`](#creating-a-custom-variable)
|
|
|
|
as exemplified above and you want to override it in a manual pipeline.
|
|
|
|
Navigate to your project's **CI/CD > Pipelines** and click **Run pipeline**.
|
|
|
|
Choose the branch you want to run the pipeline for, then add a new variable
|
|
|
|
pair through the UI:
|
|
|
|
|
|
|
|
![Override variable value](img/override_variable_manual_pipeline.png)
|
|
|
|
|
|
|
|
The Runner will override the value previously set and use the custom
|
|
|
|
value you set for this specific pipeline:
|
|
|
|
|
|
|
|
![Manually overridden variable output](img/override_value_via_manual_pipeline_output.png)
|
|
|
|
|
|
|
|
## Environment variables expressions
|
|
|
|
{: #variables-expressions}
|
|
|
|
|
|
|
|
> Introduced in GitLab 10.7.
|
|
|
|
|
|
|
|
It is possible to use variables expressions with only / except policies in
|
|
|
|
`.gitlab-ci.yml`. By using this approach you can limit what jobs are going to
|
|
|
|
be created within a pipeline after pushing a code to GitLab.
|
|
|
|
|
|
|
|
This is particularly useful in combination with variables and triggered
|
|
|
|
pipeline variables.
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
deploy:
|
|
|
|
script: cap staging deploy
|
|
|
|
environment: staging
|
|
|
|
only:
|
|
|
|
variables:
|
|
|
|
- $RELEASE == "staging"
|
|
|
|
- $STAGING
|
|
|
|
```
|
|
|
|
|
|
|
|
Each expression provided is going to be evaluated before creating a pipeline.
|
|
|
|
|
|
|
|
If any of the conditions in `variables` evaluates to truth when using `only`,
|
|
|
|
a new job is going to be created. If any of the expressions evaluates to truth
|
|
|
|
when `except` is being used, a job is not going to be created.
|
|
|
|
|
|
|
|
This follows usual rules for [`only` / `except` policies](../yaml/README.md#onlyexcept-advanced).
|
|
|
|
|
|
|
|
### Supported syntax
|
|
|
|
|
|
|
|
Below you can find supported syntax reference:
|
|
|
|
|
|
|
|
1. Equality matching using a string
|
|
|
|
|
|
|
|
> Example: `$VARIABLE == "some value"`
|
|
|
|
|
|
|
|
You can use equality operator `==` to compare a variable content to a
|
|
|
|
string. We support both, double quotes and single quotes to define a string
|
|
|
|
value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'`
|
|
|
|
are supported. `"some value" == $VARIABLE` is correct too.
|
|
|
|
|
|
|
|
1. Checking for an undefined value
|
|
|
|
|
|
|
|
> Example: `$VARIABLE == null`
|
|
|
|
|
|
|
|
It sometimes happens that you want to check whether a variable is defined
|
|
|
|
or not. To do that, you can compare a variable to `null` keyword, like
|
|
|
|
`$VARIABLE == null`. This expression is going to evaluate to truth if
|
|
|
|
variable is not defined.
|
|
|
|
|
|
|
|
1. Checking for an empty variable
|
|
|
|
|
|
|
|
> Example: `$VARIABLE == ""`
|
|
|
|
|
|
|
|
If you want to check whether a variable is defined, but is empty, you can
|
|
|
|
simply compare it against an empty string, like `$VAR == ''`.
|
|
|
|
|
|
|
|
1. Comparing two variables
|
|
|
|
|
|
|
|
> Example: `$VARIABLE_1 == $VARIABLE_2`
|
|
|
|
|
|
|
|
It is possible to compare two variables. This is going to compare values
|
|
|
|
of these variables.
|
|
|
|
|
|
|
|
1. Variable presence check
|
|
|
|
|
|
|
|
> Example: `$STAGING`
|
|
|
|
|
|
|
|
If you only want to create a job when there is some variable present,
|
|
|
|
which means that it is defined and non-empty, you can simply use
|
|
|
|
variable name as an expression, like `$STAGING`. If `$STAGING` variable
|
|
|
|
is defined, and is non empty, expression will evaluate to truth.
|
|
|
|
`$STAGING` value needs to a string, with length higher than zero.
|
|
|
|
Variable that contains only whitespace characters is not an empty variable.
|
|
|
|
|
|
|
|
1. Pattern matching _(added in 11.0)_
|
|
|
|
|
|
|
|
> Example: `$VARIABLE =~ /^content.*/`
|
|
|
|
|
|
|
|
It is possible perform pattern matching against a variable and regular
|
|
|
|
expression. Expression like this evaluates to truth if matches are found.
|
|
|
|
|
|
|
|
Pattern matching is case-sensitive by default. Use `i` flag modifier, like
|
|
|
|
`/pattern/i` to make a pattern case-insensitive.
|
|
|
|
|
2017-08-17 22:00:37 +05:30
|
|
|
## Debug tracing
|
|
|
|
|
|
|
|
> Introduced in GitLab Runner 1.7.
|
2018-03-17 18:26:18 +05:30
|
|
|
|
|
|
|
CAUTION: **Warning:**
|
|
|
|
Enabling debug tracing can have severe security implications. The
|
2018-11-08 19:23:39 +05:30
|
|
|
output **will** contain the content of all your variables and any other
|
2018-03-17 18:26:18 +05:30
|
|
|
secrets! The output **will** be uploaded to the GitLab server and made visible
|
|
|
|
in job traces!
|
2016-11-03 12:29:30 +05:30
|
|
|
|
|
|
|
By default, GitLab Runner hides most of the details of what it is doing when
|
2018-03-17 18:26:18 +05:30
|
|
|
processing a job. This behavior keeps job traces short, and prevents secrets
|
2016-11-03 12:29:30 +05:30
|
|
|
from being leaked into the trace unless your script writes them to the screen.
|
|
|
|
|
|
|
|
If a job isn't working as expected, this can make the problem difficult to
|
|
|
|
investigate; in these cases, you can enable debug tracing in `.gitlab-ci.yml`.
|
|
|
|
Available on GitLab Runner v1.7+, this feature enables the shell's execution
|
2017-08-17 22:00:37 +05:30
|
|
|
trace, resulting in a verbose job trace listing all commands that were run,
|
2016-11-03 12:29:30 +05:30
|
|
|
variables that were set, etc.
|
|
|
|
|
2017-08-17 22:00:37 +05:30
|
|
|
Before enabling this, you should ensure jobs are visible to
|
|
|
|
[team members only](../../user/permissions.md#project-features). You should
|
2019-05-18 00:54:41 +05:30
|
|
|
also [erase](../pipelines.md#accessing-individual-jobs) all generated job traces
|
2016-11-03 12:29:30 +05:30
|
|
|
before making them visible again.
|
|
|
|
|
|
|
|
To enable debug traces, set the `CI_DEBUG_TRACE` variable to `true`:
|
|
|
|
|
|
|
|
```yaml
|
2017-08-17 22:00:37 +05:30
|
|
|
job_name:
|
2016-11-03 12:29:30 +05:30
|
|
|
variables:
|
|
|
|
CI_DEBUG_TRACE: "true"
|
|
|
|
```
|
|
|
|
|
2017-08-17 22:00:37 +05:30
|
|
|
Example truncated output with debug trace set to true:
|
2016-11-03 12:29:30 +05:30
|
|
|
|
2017-08-17 22:00:37 +05:30
|
|
|
```bash
|
|
|
|
...
|
|
|
|
|
|
|
|
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/*"
|
|
|
|
else
|
|
|
|
$'\''mkdir'\'' "-p" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template"
|
|
|
|
$'\''rm'\'' "-r" "-f" "/builds/gitlab-examples/ci-debug-trace"
|
|
|
|
$'\''git'\'' "config" "-f" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template/config" "fetch.recurseSubmodules" "false"
|
|
|
|
echo $'\''\x1b[32;1mCloning repository...\x1b[0;m'\''
|
|
|
|
$'\''git'\'' "clone" "--no-checkout" "https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git" "/builds/gitlab-examples/ci-debug-trace" "--template" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template"
|
|
|
|
$'\''cd'\'' "/builds/gitlab-examples/ci-debug-trace"
|
|
|
|
fi
|
|
|
|
echo $'\''\x1b[32;1mChecking out dd648b2e as master...\x1b[0;m'\''
|
|
|
|
$'\''git'\'' "checkout" "-f" "-q" "dd648b2e48ce6518303b0bb580b2ee32fadaf045"
|
|
|
|
'
|
|
|
|
+++ hostname
|
|
|
|
++ echo 'Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-machine-1480971377-317a7d0f-digital-ocean-4gb...'
|
|
|
|
Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-machine-1480971377-317a7d0f-digital-ocean-4gb...
|
|
|
|
++ export CI=true
|
|
|
|
++ CI=true
|
2019-05-18 00:54:41 +05:30
|
|
|
++ export CI_API_V4_API_URL=https://example.com:3000/api/v4
|
|
|
|
++ CI_API_V4_API_URL=https://example.com:3000/api/v4
|
2017-08-17 22:00:37 +05:30
|
|
|
++ export CI_DEBUG_TRACE=false
|
|
|
|
++ CI_DEBUG_TRACE=false
|
|
|
|
++ export CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
|
|
|
|
++ CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
|
2019-02-15 15:39:39 +05:30
|
|
|
++ export CI_COMMIT_SHORT_SHA=dd648b2e
|
|
|
|
++ CI_COMMIT_SHORT_SHA=dd648b2e
|
2017-08-17 22:00:37 +05:30
|
|
|
++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
|
|
|
|
++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
|
|
|
|
++ export CI_COMMIT_REF_NAME=master
|
|
|
|
++ CI_COMMIT_REF_NAME=master
|
|
|
|
++ export CI_JOB_ID=7046507
|
|
|
|
++ CI_JOB_ID=7046507
|
|
|
|
++ export CI_REPOSITORY_URL=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git
|
|
|
|
++ CI_REPOSITORY_URL=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git
|
|
|
|
++ export CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx
|
|
|
|
++ CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx
|
|
|
|
++ export CI_PROJECT_ID=1796893
|
|
|
|
++ CI_PROJECT_ID=1796893
|
|
|
|
++ export CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
|
|
|
|
++ CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
|
|
|
|
++ export CI_SERVER=yes
|
|
|
|
++ CI_SERVER=yes
|
|
|
|
++ export 'CI_SERVER_NAME=GitLab CI'
|
|
|
|
++ CI_SERVER_NAME='GitLab CI'
|
|
|
|
++ export CI_SERVER_VERSION=
|
|
|
|
++ CI_SERVER_VERSION=
|
2018-12-05 23:21:45 +05:30
|
|
|
++ export CI_SERVER_VERSION_MAJOR=
|
|
|
|
++ CI_SERVER_VERSION_MAJOR=
|
|
|
|
++ export CI_SERVER_VERSION_MINOR=
|
|
|
|
++ CI_SERVER_VERSION_MINOR=
|
|
|
|
++ export CI_SERVER_VERSION_PATCH=
|
|
|
|
++ CI_SERVER_VERSION_PATCH=
|
2017-08-17 22:00:37 +05:30
|
|
|
++ export CI_SERVER_REVISION=
|
|
|
|
++ CI_SERVER_REVISION=
|
|
|
|
++ export GITLAB_CI=true
|
|
|
|
++ GITLAB_CI=true
|
|
|
|
++ export CI=true
|
|
|
|
++ CI=true
|
2019-05-18 00:54:41 +05:30
|
|
|
++ export CI_API_V4_API_URL=https://example.com:3000/api/v4
|
|
|
|
++ CI_API_V4_API_URL=https://example.com:3000/api/v4
|
2017-08-17 22:00:37 +05:30
|
|
|
++ export GITLAB_CI=true
|
|
|
|
++ GITLAB_CI=true
|
|
|
|
++ export CI_JOB_ID=7046507
|
|
|
|
++ CI_JOB_ID=7046507
|
|
|
|
++ export CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx
|
|
|
|
++ CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx
|
|
|
|
++ export CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045
|
|
|
|
++ CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045
|
|
|
|
++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
|
|
|
|
++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
|
|
|
|
++ export CI_COMMIT_REF_NAME=master
|
|
|
|
++ CI_COMMIT_REF_NAME=master
|
|
|
|
++ export CI_COMMIT_NAME=debug_trace
|
|
|
|
++ CI_JOB_NAME=debug_trace
|
|
|
|
++ export CI_JOB_STAGE=test
|
|
|
|
++ CI_JOB_STAGE=test
|
|
|
|
++ export CI_SERVER_NAME=GitLab
|
|
|
|
++ CI_SERVER_NAME=GitLab
|
|
|
|
++ export CI_SERVER_VERSION=8.14.3-ee
|
|
|
|
++ CI_SERVER_VERSION=8.14.3-ee
|
|
|
|
++ export CI_SERVER_REVISION=82823
|
|
|
|
++ CI_SERVER_REVISION=82823
|
2019-03-02 22:35:43 +05:30
|
|
|
++ export CI_PAGES_DOMAIN=gitlab.io
|
|
|
|
++ CI_PAGES_DOMAIN=gitlab.io
|
|
|
|
++ export CI_PAGES_URL=https://gitlab-examples.gitlab.io/ci-debug-trace
|
|
|
|
++ CI_PAGES_URL=https://gitlab-examples.gitlab.io/ci-debug-trace
|
2017-08-17 22:00:37 +05:30
|
|
|
++ export CI_PROJECT_ID=17893
|
|
|
|
++ CI_PROJECT_ID=17893
|
|
|
|
++ export CI_PROJECT_NAME=ci-debug-trace
|
|
|
|
++ CI_PROJECT_NAME=ci-debug-trace
|
|
|
|
++ export CI_PROJECT_PATH=gitlab-examples/ci-debug-trace
|
|
|
|
++ CI_PROJECT_PATH=gitlab-examples/ci-debug-trace
|
|
|
|
++ export CI_PROJECT_NAMESPACE=gitlab-examples
|
|
|
|
++ CI_PROJECT_NAMESPACE=gitlab-examples
|
|
|
|
++ export CI_PROJECT_URL=https://example.com/gitlab-examples/ci-debug-trace
|
|
|
|
++ CI_PROJECT_URL=https://example.com/gitlab-examples/ci-debug-trace
|
|
|
|
++ export CI_PIPELINE_ID=52666
|
|
|
|
++ CI_PIPELINE_ID=52666
|
2018-11-08 19:23:39 +05:30
|
|
|
++ export CI_PIPELINE_IID=123
|
|
|
|
++ CI_PIPELINE_IID=123
|
2017-08-17 22:00:37 +05:30
|
|
|
++ export CI_RUNNER_ID=1337
|
|
|
|
++ CI_RUNNER_ID=1337
|
|
|
|
++ export CI_RUNNER_DESCRIPTION=shared-runners-manager-1.example.com
|
|
|
|
++ CI_RUNNER_DESCRIPTION=shared-runners-manager-1.example.com
|
|
|
|
++ export 'CI_RUNNER_TAGS=shared, docker, linux, ruby, mysql, postgres, mongo'
|
|
|
|
++ CI_RUNNER_TAGS='shared, docker, linux, ruby, mysql, postgres, mongo'
|
|
|
|
++ export CI_REGISTRY=registry.example.com
|
|
|
|
++ CI_REGISTRY=registry.example.com
|
|
|
|
++ export CI_DEBUG_TRACE=true
|
|
|
|
++ CI_DEBUG_TRACE=true
|
|
|
|
++ export GITLAB_USER_ID=42
|
|
|
|
++ GITLAB_USER_ID=42
|
|
|
|
++ export GITLAB_USER_EMAIL=user@example.com
|
|
|
|
++ GITLAB_USER_EMAIL=user@example.com
|
|
|
|
++ export VERY_SECURE_VARIABLE=imaverysecurevariable
|
|
|
|
++ VERY_SECURE_VARIABLE=imaverysecurevariable
|
|
|
|
++ mkdir -p /builds/gitlab-examples/ci-debug-trace.tmp
|
|
|
|
++ echo -n '-----BEGIN CERTIFICATE-----
|
|
|
|
MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw'
|
|
|
|
|
|
|
|
...
|
|
|
|
```
|
2015-09-25 12:07:36 +05:30
|
|
|
|
2018-11-08 19:23:39 +05:30
|
|
|
[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 "Simple protection of CI variables"
|
|
|
|
[eep]: https://about.gitlab.com/pricing/ "Available only in GitLab Premium"
|
2017-09-10 17:25:29 +05:30
|
|
|
[envs]: ../environments.md
|
|
|
|
[protected branches]: ../../user/project/protected_branches.md
|
|
|
|
[protected tags]: ../../user/project/protected_tags.md
|
|
|
|
[shellexecutors]: https://docs.gitlab.com/runner/executors/
|
2016-06-02 11:05:42 +05:30
|
|
|
[triggered]: ../triggers/README.md
|
2018-10-15 14:42:47 +05:30
|
|
|
[gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token
|
2018-11-18 11:00:15 +05:30
|
|
|
[registry]: ../../user/project/container_registry.md
|
2018-11-20 20:47:30 +05:30
|
|
|
[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories
|