From aa4091ab778a89814d1b531bc0c7bc63c955a147 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Tue, 11 Apr 2023 14:12:08 +0900 Subject: [PATCH 1/7] Add initial docs for spec and with --- doc/ci/yaml/includes.md | 93 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 1 deletion(-) diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 252cef0aa97772..13ee7735c18c6b 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab CI/CD include examples **(FREE)** +# Use CI/CD configuration from other files **(FREE)** You can use [`include`](index.md#include) to include external YAML files in your CI/CD jobs. @@ -503,6 +503,97 @@ When the pipeline runs, GitLab: include: 'configs/**/*.yml' ``` +## Define inputs for configuration added with `include` (Alpha) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as an Alpha feature. + +FLAG: +`spec` and `with` are experimental [Alpha features](../../policy/alpha-beta-support.md#alpha-features) +and subject to change without notice. + +### Define input parameters with `spec:inputs` + +Use `spec:inputs` to define input parameters for CI/CD configuration intended to be added +to a pipeline with `include`. Use [`include:with`](#set-input-parameter-values-with-includewith) +to define the values to use when the pipeline runs. + +The specs must be declared at the top of the configuration file, in a header section. +Separate the header from the rest of the configuration with `---`. + +Use the interpolation format `$[[ input-name ]]` to reference the values outside of the header section. +The values are replaced with the inputs at runtime. For example: + +```yaml +spec: + inputs: + environment: +--- + +"run-tests-$[[ inputs.environment ]]": + script: ./run-test + +scan-website: + script: ./scan-website $[[ inputs.environment ]] + rules: + - if: $[[ inputs.environment ]] == 'staging' + - if: $[[ inputs.environment ]] == 'production' +``` + +Inputs in `spec:inputs`: + +- Are mandatory by default. +- Can be made optional by specifying a `default`. Use `default: null` to have a default value. +- Can be limited to a set of options with `options`. + +For example: + +```yaml +spec: + inputs: + website: + user: + default: test-user + flags: + default: null + test_run: + options: + - unit + - integration + - system + environment: + options: + - staging + - canary + - production + default: staging +--- + +# The pipeline configuration would follow... +``` + +In this example: + +- `website` is mandatory and must be defined. +- `user` is optional. If not defined, the value is `test-user` +- `flags` is optional. If not defined, it has no value. +- `test_run` run is mandatory, and must be one of `unit`, `integration`, or `system`. +- `environment` is optional. If not defined, the value is `staging`. If defined, + it must be one of `staging`, `canary`, or `production`. + +### Set input parameter values with `include:with` + +Use `include:with` to set the values for the parameters when the included configuration +is added to the pipeline. For example: + +```yaml +include: + - local: 'custome_configuration.yml' + with: + website: "My website" + test_run: system + flags: $PIPELINE_FLAGS # CI/CD variable expansion is supported +``` + ## Troubleshooting ### `Maximum of 150 nested includes are allowed!` error -- GitLab From e73046f18096b11a9965bca09c22173127cb16ee Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Tue, 11 Apr 2023 16:21:34 +0900 Subject: [PATCH 2/7] Remove details about optional --- doc/ci/yaml/includes.md | 30 ++++++++---------------------- 1 file changed, 8 insertions(+), 22 deletions(-) diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 13ee7735c18c6b..1d44dfe0d72355 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -503,12 +503,12 @@ When the pipeline runs, GitLab: include: 'configs/**/*.yml' ``` -## Define inputs for configuration added with `include` (Alpha) +## Define inputs for configuration added with `include` (Beta) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as an Alpha feature. FLAG: -`spec` and `with` are experimental [Alpha features](../../policy/alpha-beta-support.md#alpha-features) +`spec` and `with` are experimental [Open Beta features](../../policy/alpha-beta-support.md#open-beta-features) and subject to change without notice. ### Define input parameters with `spec:inputs` @@ -520,8 +520,9 @@ to define the values to use when the pipeline runs. The specs must be declared at the top of the configuration file, in a header section. Separate the header from the rest of the configuration with `---`. -Use the interpolation format `$[[ input-name ]]` to reference the values outside of the header section. -The values are replaced with the inputs at runtime. For example: +Use the interpolation format `$[[ input.input-id ]]` to reference the values outside of the header section. +The inputs are evaluated and interpolated once, when the configuration is fetched +during pipeline creation. ```yaml spec: @@ -542,8 +543,7 @@ scan-website: Inputs in `spec:inputs`: - Are mandatory by default. -- Can be made optional by specifying a `default`. Use `default: null` to have a default value. -- Can be limited to a set of options with `options`. +- Can be made optional by specifying a `default`. Use `default: null` to have no default value. For example: @@ -552,20 +552,9 @@ spec: inputs: website: user: - default: test-user + default: 'test-user' flags: default: null - test_run: - options: - - unit - - integration - - system - environment: - options: - - staging - - canary - - production - default: staging --- # The pipeline configuration would follow... @@ -576,9 +565,6 @@ In this example: - `website` is mandatory and must be defined. - `user` is optional. If not defined, the value is `test-user` - `flags` is optional. If not defined, it has no value. -- `test_run` run is mandatory, and must be one of `unit`, `integration`, or `system`. -- `environment` is optional. If not defined, the value is `staging`. If defined, - it must be one of `staging`, `canary`, or `production`. ### Set input parameter values with `include:with` @@ -590,7 +576,7 @@ include: - local: 'custome_configuration.yml' with: website: "My website" - test_run: system + user: "test-user-2" flags: $PIPELINE_FLAGS # CI/CD variable expansion is supported ``` -- GitLab From d4d27c69fc6581b9c2eeb6db45de7f5e787bfdf4 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Wed, 12 Apr 2023 00:39:21 +0900 Subject: [PATCH 3/7] Clarify example and remove variable --- doc/ci/yaml/includes.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 1d44dfe0d72355..6325ff074348b0 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -505,7 +505,7 @@ When the pipeline runs, GitLab: ## Define inputs for configuration added with `include` (Beta) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as an Alpha feature. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a Beta feature. FLAG: `spec` and `with` are experimental [Open Beta features](../../policy/alpha-beta-support.md#open-beta-features) @@ -545,7 +545,7 @@ Inputs in `spec:inputs`: - Are mandatory by default. - Can be made optional by specifying a `default`. Use `default: null` to have no default value. -For example: +For example, a `custom_configuration.yml`: ```yaml spec: @@ -569,17 +569,24 @@ In this example: ### Set input parameter values with `include:with` Use `include:with` to set the values for the parameters when the included configuration -is added to the pipeline. For example: +is added to the pipeline. + +For example, to include a `custom_configuration.yml` that has the same specs +as the [example above](#define-input-parameters-with-specinputs): ```yaml include: - - local: 'custome_configuration.yml' + - local: 'custom_configuration.yml' with: website: "My website" - user: "test-user-2" - flags: $PIPELINE_FLAGS # CI/CD variable expansion is supported ``` +In this example: + +- `website` has a value of `My website` for the included configuration. +- `user` has a value of `test-user`, because that is the default when not specified. +- `flags` has no value, because it is optional and has no default when not specified. + ## Troubleshooting ### `Maximum of 150 nested includes are allowed!` error -- GitLab From cdd09b00a9d0cc4360cde785f730dad6842da8a4 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Wed, 12 Apr 2023 19:58:42 +0900 Subject: [PATCH 4/7] Add limit details --- doc/ci/yaml/includes.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 6325ff074348b0..ca5ee82b94c002 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -508,7 +508,7 @@ When the pipeline runs, GitLab: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a Beta feature. FLAG: -`spec` and `with` are experimental [Open Beta features](../../policy/alpha-beta-support.md#open-beta-features) +`spec` and `with` are experimental [Open Beta features](../../policy/alpha-beta-support.md#beta) and subject to change without notice. ### Define input parameters with `spec:inputs` @@ -540,10 +540,12 @@ scan-website: - if: $[[ inputs.environment ]] == 'production' ``` -Inputs in `spec:inputs`: +When using `spec:inputs`: -- Are mandatory by default. -- Can be made optional by specifying a `default`. Use `default: null` to have no default value. +- Inputs are mandatory by default. +- Inputs can be made optional by specifying a `default`. Use `default: null` to have no default value. +- A string containing an interpolation block must not be more than 1 MB. +- The string inside an interpolation block must be less than 1 KB. For example, a `custom_configuration.yml`: -- GitLab From 845723c289f5eb997d44cb7a38fffcbf2d043f63 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Fri, 14 Apr 2023 07:07:47 +0000 Subject: [PATCH 5/7] Apply 3 suggestion(s) to 1 file(s) --- doc/ci/yaml/includes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index ca5ee82b94c002..123ae36ef23745 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -522,7 +522,7 @@ Separate the header from the rest of the configuration with `---`. Use the interpolation format `$[[ input.input-id ]]` to reference the values outside of the header section. The inputs are evaluated and interpolated once, when the configuration is fetched -during pipeline creation. +during pipeline creation, but before the configuration is merged with the contents of the `.gitlab-ci.yml`. ```yaml spec: @@ -544,7 +544,7 @@ When using `spec:inputs`: - Inputs are mandatory by default. - Inputs can be made optional by specifying a `default`. Use `default: null` to have no default value. -- A string containing an interpolation block must not be more than 1 MB. +- A string containing an interpolation block must not exceed 1 MB. - The string inside an interpolation block must be less than 1 KB. For example, a `custom_configuration.yml`: @@ -565,7 +565,7 @@ spec: In this example: - `website` is mandatory and must be defined. -- `user` is optional. If not defined, the value is `test-user` +- `user` is optional. If not defined, the value is `test-user`. - `flags` is optional. If not defined, it has no value. ### Set input parameter values with `include:with` -- GitLab From 52bf50204e2c3c4a5f845955b8580a5167a808c3 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Fri, 14 Apr 2023 16:17:51 +0900 Subject: [PATCH 6/7] Simplify inputs example --- doc/ci/yaml/includes.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 123ae36ef23745..61e6b52aa4ab3a 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -528,16 +528,12 @@ during pipeline creation, but before the configuration is merged with the conten spec: inputs: environment: + job-stage: --- -"run-tests-$[[ inputs.environment ]]": - script: ./run-test - scan-website: script: ./scan-website $[[ inputs.environment ]] - rules: - - if: $[[ inputs.environment ]] == 'staging' - - if: $[[ inputs.environment ]] == 'production' + stage: $[[ inputs.job-stage ]] ``` When using `spec:inputs`: -- GitLab From b1621449c72154e750510d42af43a1df0508585b Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Fri, 14 Apr 2023 08:11:29 +0000 Subject: [PATCH 7/7] Apply 3 suggestion(s) to 1 file(s) --- doc/ci/yaml/includes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 61e6b52aa4ab3a..941484008969fc 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -532,16 +532,16 @@ spec: --- scan-website: - script: ./scan-website $[[ inputs.environment ]] stage: $[[ inputs.job-stage ]] + script: ./scan-website $[[ inputs.environment ]] ``` When using `spec:inputs`: -- Inputs are mandatory by default. +- Defined inputs are mandatory by default. - Inputs can be made optional by specifying a `default`. Use `default: null` to have no default value. - A string containing an interpolation block must not exceed 1 MB. -- The string inside an interpolation block must be less than 1 KB. +- The string inside an interpolation block must not exceed 1 KB. For example, a `custom_configuration.yml`: -- GitLab