@@ -286,7 +286,7 @@ The following documentation relates to the DevOps **Release** stage:
| [Canary Deployments](user/project/canary_deployments.md)**(PREMIUM)** | Employ a popular CI strategy where a small portion of the fleet is updated to the new version first. |
| [Deploy Boards](user/project/deploy_boards.md)**(PREMIUM)** | View the current health and status of each CI environment running on Kubernetes, displaying the status of the pods in the deployment. |
| [Environments and deployments](ci/environments.md) | With environments, you can control the continuous deployment of your software within GitLab. |
| [Environment-specific variables](ci/variables/README.md#limiting-environment-scopes-of-environment-variables) | Limit the scope of variables to specific environments. |
| [Environment-specific variables](ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) | Limit the scope of variables to specific environments. |
| [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Deployment and Delivery with GitLab. |
| [GitLab Pages](user/project/pages/index.md) | Build, test, and deploy a static site directly from GitLab. |
| [Protected Runners](ci/runners/README.md#protected-runners) | Select Runners to only pick jobs for protected branches and tags. |
...
...
@@ -315,7 +315,7 @@ The following documentation relates to the DevOps **Configure** stage:
| [Installing Applications](user/project/clusters/index.md#installing-applications) | Deploy Helm, Ingress, and Prometheus on Kubernetes. |
| [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) | Enable and use slash commands from within Mattermost. |
| [Multiple Kubernetes Clusters](user/project/clusters/index.md#multiple-kubernetes-clusters-premium)**(PREMIUM)** | Associate more than one Kubernetes clusters to your project. |
| [Protected variables](ci/variables/README.md#protected-environment-variables) | Restrict variables to protected branches and tags. |
| [Protected variables](ci/variables/README.md#protect-a-custom-variable) | Restrict variables to protected branches and tags. |
| [Serverless](user/project/clusters/serverless/index.md) | Run serverless workloads on Kubernetes. |
| [Slack slash commands](user/project/integrations/slack_slash_commands.md) | Enable and use slash commands from within Slack. |
| [Manage your infrastructure with Terraform](user/infrastructure/index.md) | Manage your infrastructure as you run your CI/CD pipeline. |
@@ -925,7 +925,7 @@ with `review/` would have that particular variable.
Some GitLab features can behave differently for each environment.
For example, you can
[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables).
[create a secret variable to be injected only into a production environment](variables/README.md#limit-the-environment-scopes-of-environment-variables).
In most cases, these features use the _environment specs_ mechanism, which offers
an efficient way to implement scoping within each environment group.
There are [some predefined variables](#custom-variables-validated-by-gitlab) of this type, which may be further validated. They will appear when you add or update a variable.
##### File type
The example above can now be simplified by creating a "File" type variable, and using
it directly. For example, let's say we have the following variables:
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
instance and you want to know what domain your GitLab Pages are
served under. You can call it by using the predefined
variable `$CI_PAGES_DOMAIN` in your script:
```yaml
...
...
@@ -176,47 +68,54 @@ 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
## Custom environment variables
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.
When you need a specific custom environment variable, you can
[set it up in the UI](#create-a-custom-variable-in-the-ui), in [the API](../../api/project_level_variables.md),
or directly [in the `.gitlab-ci.yml` file](#create-a-custom-variable-in-gitlab-ciyml).
You can either set the variable directly in the `.gitlab-ci.yml`
file or through the UI.
The variables are used by the Runner any time the pipeline runs.
You can also [override variable values manually for a specific pipeline](../pipelines/index.md#specifying-variables-when-running-manual-jobs).
NOTE: **Note:**
It is possible to [specify variables when running manual jobs](../pipelines/index.md#specifying-variables-when-running-manual-jobs).
There are two types of variables: **Variable** and **File**. You cannot set types in
the `.gitlab-ci.yml` file, but you can set them in the UI and API.
#### Via `.gitlab-ci.yml`
### Create a custom variable in `.gitlab-ci.yml`
To create a new custom `env_var` variable via [`.gitlab-ci.yml`](../yaml/README.md#variables), define their variable/value pair under
`variables`:
To create a custom `env_var` variable in the [`.gitlab-ci.yml`](../yaml/README.md#variables) file,
define the variable/value pair under `variables`:
```yaml
variables:
TEST:"HELLOWORLD"
```
For a deeper look into them, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined-variables).
You can then call its value in your script:
```yaml
script:
-echo "$TEST"
```
For more details, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined-variables).
#### Via the UI
### Create a custom variable in the UI
From within the UI, you can add or update custom environment variables:
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:
1. Click the **Add Variable** button. In the **Add variable** modal, fill in the details:
- **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.
- **Protect variable** (Optional): If selected, the variable will only be available in pipelines that run on protected branches or tags.
- **Mask variable** (Optional): If selected, the variable's **Value** will be masked in job logs. The variable will fail to save if the value does not meet the [masking requirements](#masked-variables).
- **Mask variable** (Optional): If selected, the variable's **Value** will be masked in job logs. The variable fails to save 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 on the **{pencil}****Edit** button.
After a variable is created, you can update any of the details by clicking the **{pencil}****Edit** button.
Once you've set the variables, call them from the `.gitlab-ci.yml` file:
After you set a variable, call it from the `.gitlab-ci.yml` file:
You can't mask variables that don't meet these requirements.
### Protect a custom variable
> Introduced in GitLab 9.3.
Variables can be protected. When a variable is
protected, it is securely passed to pipelines running on
[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md) only. The other pipelines do not get
the protected variable.
To protect a variable:
1. Go to **Settings > CI/CD**.
1. Expand the **Variables** section.
1. Next to the variable you want to protect, click **Edit**.
1. Select the **Protect variable** check box.
1. Click **Update variable**.
The variable is available for all subsequent pipelines.
### Custom variables validated by GitLab
Some variables are listed in the UI so you can choose them more quickly.
GitLab validates the values of these variables to ensure they are in the correct format.
@@ -426,22 +428,7 @@ Click [here](where_variables_can_be_used.md) for a section that describes where
## Advanced use
### Protected environment variables
> Introduced in GitLab 9.3.
Variables can be protected. Whenever a variable is
protected, it would only be securely passed to pipelines running on the
[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md). The other pipelines would not get any
protected variables.
Protected variables can be added by going to your project's
**Settings > CI/CD**, then finding the section called
**Variables**, and check "Protected".
Once you set them, they will be available for all subsequent pipelines.
### Limiting environment scopes of environment variables
### Limit the environment scopes of environment variables
You can limit the environment scope of a variable by
[defining which environments](../environments.md) it can be available for.
...
...
@@ -478,22 +465,23 @@ CAUTION: **Caution:**
Variables with multiline values are not currently supported due to
limitations with the current Auto DevOps scripting environment.
### Environment variables triggered manually
### Override a variable by manually running a pipeline
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/44059) in GitLab 10.8.
[Manually triggered pipelines](../pipelines/index.md#run-a-pipeline-manually) allow you to override the value of a current variable.
You can override the value of a current variable by
[running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually).
For instance, suppose you added a custom variable named `$TEST`
@@ -502,10 +490,10 @@ value you set for this specific pipeline:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyexcept-advanced)
> - [Expanded](https://gitlab.com/gitlab-org/gitlab/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules)
Variable expressions can be used to limit what jobs are going to be created
within a pipeline after pushing changes to GitLab.
Use variable expressions to limit which jobs are created
within a pipeline after changes are pushed to GitLab.
In `.gitlab-ci.yml`, they work with both
In `.gitlab-ci.yml`, variable expressions work with both:
-[`rules`](../yaml/README.md#rules), which is the recommended approach, and
-[`only` and `except`](../yaml/README.md#onlyexcept-basic), which are candidates for deprecation.
...
...
@@ -523,15 +511,15 @@ deploy:
-$STAGING
```
Each expression provided is going to be evaluated before creating a pipeline.
Each expression provided is evaluated before a pipeline is created.
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.
If any of the conditions in `variables` evaluates to true when using `only`,
a new job is created. If any of the expressions evaluates to true
when `except` is being used, a job is not created.
This follows usual rules for [`only` / `except` policies](../yaml/README.md#onlyexcept-advanced).
This follows the usual rules for [`only` / `except` policies](../yaml/README.md#onlyexcept-advanced).
### Supported syntax
### Syntax of environment variable expressions
Below you can find supported syntax reference:
...
...
@@ -679,7 +667,7 @@ 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
log, resulting in a verbose job log listing all commands that were run,
variables that were set, etc.
variables that were set, and so on.
Before enabling this, you should ensure jobs are visible to
[team members only](../../user/permissions.md#project-features). You should
@@ -76,7 +76,7 @@ The next step is to tell the offline instance to use these resources instead of
and so on.
You can set these variables in the project's `.gitlab-ci.yml` files by using the bundle directly, or
in the GitLab UI at the project or group level. See the [GitLab CI/CD environment variables page](../../ci/variables/README.md#creating-a-custom-environment-variable)
in the GitLab UI at the project or group level. See the [GitLab CI/CD environment variables page](../../ci/variables/README.md#custom-environment-variables)
@@ -146,7 +146,7 @@ to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `--
## Custom Helm chart per environment
You can specify the use of a custom Helm chart per environment by scoping the environment variable
to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables).
to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables).
