diff options
author | Grzegorz Bizon <grzesiek.bizon@gmail.com> | 2018-03-28 15:00:53 +0300 |
---|---|---|
committer | Grzegorz Bizon <grzesiek.bizon@gmail.com> | 2018-03-28 15:00:53 +0300 |
commit | 6ed2370b850ea6db22649ed32940acdc2010877b (patch) | |
tree | add845cfaf59dfcb460a3ce17c2201f9118ce0cf /doc/ci | |
parent | 4cc4959e3d8c510a8cf3309d2d2d40688501ea6d (diff) |
Add basic docs for variables expressions feature
Diffstat (limited to 'doc/ci')
-rw-r--r-- | doc/ci/variables/README.md | 62 | ||||
-rw-r--r-- | doc/ci/yaml/README.md | 26 |
2 files changed, 85 insertions, 3 deletions
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index bd4aeb006bd..25ec12a5b3e 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -449,6 +449,67 @@ export CI_REGISTRY_USER="gitlab-ci-token" export CI_REGISTRY_PASSWORD="longalfanumstring" ``` +## Variables expressions + +> Variables expressions were added 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 builds are going to +be created within a pipeline after pushing code to GitLab. + +This is particularly useful in combination with secret variables and triggered +pipeline variables. + +```yaml +deploy: + script: cap staging deploy + environment: staging + only: + variables: + - $RELEASE == "staging" + - $STAGING +``` + +Each provided variables expression is going to be evaluated before creating +a pipeline. + +If any of the conditions in `variables` evaluates to truth when using `only`, +new build is going to be created. If any of the expressions evaluates to truth +when `except` is being used, a build is not going to be created. + +This follows usual rules for [`only` / `except` policies][build policies]. + +### Supported syntax + +Below you can find currently 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. + + It sometimes happens that you want to check whether variable is defined or + not. To do that, you can compare variable to `null` value, like + `$VARIABLE == null`. This expression is going to evaluate to truth if + variable is not set. + +1. Comparing two variables. + + It is possible to compare two variables. `$VARIABLE_1 == $VARIABLE_2`. + +1. Variable presence check. + + 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. + [ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 "Simple protection of CI secret variables" [eep]: https://about.gitlab.com/products/ "Available only in GitLab Premium" [envs]: ../environments.md @@ -459,3 +520,4 @@ export CI_REGISTRY_PASSWORD="longalfanumstring" [triggered]: ../triggers/README.md [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger [subgroups]: ../../user/group/subgroups/index.md +[build policies]: ../yaml/#only-and-except-complex diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 7184f3367be..2171da419d1 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -315,9 +315,14 @@ policy configuration. GitLab now supports both, simple and complex strategies, so it is possible to use an array and a hash configuration scheme. -Two keys are now available: `refs` and `kubernetes`. Refs strategy equals to -simplified only/except configuration, whereas kubernetes strategy accepts only -`active` keyword. +Three keys are now available: `refs`, `kubernetes` and `variables`. +Refs strategy equals to simplified only/except configuration, whereas +kubernetes strategy accepts only `active` keyword. + +`variables` keyword is used to define variables expressions. In other words +you can use predefined variables / secret variables / project / group or +environment-scoped variables to define an expression GitLab is going to +evaluate in order to decide whether a job should be created or not. See the example below. Job is going to be created only when pipeline has been scheduled or runs for a `master` branch, and only if kubernetes service is @@ -332,6 +337,20 @@ job: kubernetes: active ``` +Example of using variables expressions: + +```yaml +deploy: + only: + refs: + - branches + variables: + - $RELEASE == "staging" + - $STAGING +``` + +Learn more about variables expressions on [separate page][variables-expressions]. + ## `tags` `tags` is used to select specific Runners from the list of all Runners that are @@ -1549,3 +1568,4 @@ CI with various languages. [ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447 [ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909 [schedules]: ../../user/project/pipelines/schedules.md +[variables expressions]: ../variables#variables-expressions |