Backend: Implement `spec:inputs:` prerequisite for CI components
Context
Previous discussions #377327 (closed) and !105817 (merged)
Proposal
As a first deliverable to start the implementation of CI components, we would like to allow the include:
syntax to support input parameters. In the architecture blueprint we decided that a YAML configuration containing inputs:
syntax requires the YAML including it to indicate input parameters using include:*:with
syntax.
This proposal does not introduce any new component but leverages the existing capabilities our users use today using include:
.
# .gitlab-ci.yml
include:
- local: file.yml # support all include (local, project, remote, template, trigger: include, trigger: project)
with:
website: http://example.com
# file.yml to be included
spec:
inputs:
website: # required input. By default, all inputs are required.
stage:
default: test # optional input.
---
# rest of the configuration content.
job1:
stage: $[[ inputs.stage ]] # inputs interpolation.
script: "./do-something $[[ inputs.website ]]"
job2:
stage: $[[ inputs.stage ]]
script: ./do-something-else
irb(main):002:0> YAML.load_stream(File.read('file.yml'))
=> [{"inputs"=>{"website"=>nil, "stage"=>{"default"=>"test"}}}, {"job1"=>{"stage"=>"$[[ inputs.stage ]]", "script"=>"./do-something $[[ inputs.website ]]"}, "job2"=>{"stage"=>"$[[ inputs.stage ]]", "script"=>"./do-something-else"}}]
spec:
inputs:
variable: KEY
---
rspec:
script: echo Hello World
The MVC will consist of:
- Supporting
spec:inputs:
- Mandatory inputs
- Default inputs
- Support using
with:
on all existingincludes:
(local, project, remote, template, trigger: include, trigger: project)- when optional inputs are provided they override the default value.
- Support inputs interpolation via
$[[ inputs.XXX ]]
syntax. Inputs are interpolated immediately after reading the file to include and before merging the YAML with the main configuration.
Validation
If someone uses with:
but the including YAML doesn't specify spec:inputs:
that should fail:
With: | Inputs: | Result |
---|---|---|
error |
||
validate inputs | ||
use default: | ||
Legacy include without inputs:
|
Out of scope (for consideration)
- Variable expansion on
inputs:
. -
inputs:
on the main.gitlab-ci.yml
(we will not support nor should we raise an error oninputs:
as top level keyword in the main pipeline). - Pre-fill
Run Pipeline
form with inputs (like pre-fill variables). - Multiple inputs (
options:
). - Input type validation.
Implementation Table
Title | MR Link | Done? |
---|---|---|
Add parser for multi-document YAML files | !109137 (merged) | |
Update External::File::Base to accept multi-document YAML |
!111221 (closed) | |
Add interpolation to CI configurations | !107208 (merged) | |
Add Entry for spec:inputs: (including defaults) |
||
Add Entry for with: (including validations) |
||
Document new keywords |
Edited by Avielle Wolfe