From 6ed2370b850ea6db22649ed32940acdc2010877b Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Wed, 28 Mar 2018 14:00:53 +0200 Subject: Add basic docs for variables expressions feature --- doc/ci/variables/README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) (limited to 'doc/ci/variables') 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 -- cgit v1.2.1 From f4d81536ac26f75e0aad248ad95c31c9e1f2680b Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Thu, 29 Mar 2018 11:25:49 +0200 Subject: Copy-edit documentation for variables expressions --- doc/ci/variables/README.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) (limited to 'doc/ci/variables') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 25ec12a5b3e..9f268f47e6f 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -474,16 +474,16 @@ 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. +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][build policies]. +This follows usual rules for `only` / `except` policies. ### Supported syntax Below you can find currently supported syntax reference: -1. Equality matching using a string. +1. Equality matching using a string Example: `$VARIABLE == "some value"` @@ -492,18 +492,23 @@ Below you can find currently supported syntax reference: value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'` are supported. `"some value" == $VARIABLE` is correct too. -1. Checking for an undefined value. +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. +1. Checking for an empty 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 It is possible to compare two variables. `$VARIABLE_1 == $VARIABLE_2`. -1. Variable presence check. +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 @@ -520,4 +525,3 @@ Below you can find currently supported syntax reference: [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 -- cgit v1.2.1 From 323bac4a6e1de5d9ba9c1cb3a2868f514888c44a Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Thu, 5 Apr 2018 11:30:02 +0200 Subject: Improve docs about pipeline variables expressions --- doc/ci/variables/README.md | 55 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 11 deletions(-) (limited to 'doc/ci/variables') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 9f268f47e6f..381405a9db9 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -454,8 +454,8 @@ export CI_REGISTRY_PASSWORD="longalfanumstring" > 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. +`.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 secret variables and triggered pipeline variables. @@ -470,22 +470,21 @@ deploy: - $STAGING ``` -Each provided variables expression is going to be evaluated before creating -a pipeline. +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. +This follows usual rules for [`only` / `except` policies][builds-policies]. ### Supported syntax -Below you can find currently supported syntax reference: +Below you can find supported syntax reference: 1. Equality matching using a string - Example: `$VARIABLE == "some value"` + > 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 @@ -494,26 +493,59 @@ Below you can find currently supported syntax reference: 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 + > 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 set. + 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 - It is possible to compare two variables. `$VARIABLE_1 == $VARIABLE_2`. + > 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. + +### Unsupported predefined variables + +Because GitLab evaluates variables before creating jobs, we do not support a +few variables that depend on persistence layer, like `$CI_JOB_ID`. + +Environments (like `production` or `staging`) are also being created based on +what jobs pipeline consists of, thus some environment-specific variables are +not supported as well. + +We do not support variables containing tokens because of security reasons. + +You can find a full list of unsupported variables below: + +- `CI_JOB_ID` +- `CI_JOB_TOKEN` +- `CI_BUILD_ID` +- `CI_BUILD_TOKEN` +- `CI_REGISTRY_USER` +- `CI_REGISTRY_PASSWORD` +- `CI_REPOSITORY_URL` +- `CI_ENVIRONMENT_URL` [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" @@ -525,3 +557,4 @@ Below you can find currently supported syntax reference: [triggered]: ../triggers/README.md [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger [subgroups]: ../../user/group/subgroups/index.md +[builds-policies]: ../yaml/README.md#only-and-except-complex -- cgit v1.2.1 From 847f1667c89831213859d62ca66fbd55181fb129 Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Fri, 6 Apr 2018 10:41:58 +0200 Subject: Document unsupported variables for dynamic environments --- doc/ci/variables/README.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/ci/variables') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 381405a9db9..4a504a98902 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -547,6 +547,9 @@ You can find a full list of unsupported variables below: - `CI_REPOSITORY_URL` - `CI_ENVIRONMENT_URL` +These variables are also not supported in a contex of a +[dynamic environment name][dynamic-environments]. + [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 @@ -558,3 +561,4 @@ You can find a full list of unsupported variables below: [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger [subgroups]: ../../user/group/subgroups/index.md [builds-policies]: ../yaml/README.md#only-and-except-complex +[dynamic-environments]: ../environments.md#dynamic-environments -- cgit v1.2.1