diff --git a/doc/ci/yaml/inputs.md b/doc/ci/yaml/inputs.md index 1af53d666ce407189c0eadd4ca346b4c996d8999..0eb8278fc48c3aa9305f541e4efec004f9452192 100644 --- a/doc/ci/yaml/inputs.md +++ b/doc/ci/yaml/inputs.md @@ -14,6 +14,8 @@ and subject to change without notice. ## Define input parameters with `spec:inputs` +> `description` keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415637) in GitLab 16.5. + Use `spec:inputs` to define input parameters for CI/CD configuration intended to be added to a pipeline with `include`. Use [`include:inputs`](#set-input-parameter-values-with-includeinputs) to define the values to use when the pipeline runs. @@ -41,6 +43,7 @@ When using `spec:inputs`: - Defined inputs are mandatory by default. - Inputs can be made optional by specifying a `default`. Use `default: null` to have no default value. +- You can optionally use `description` to give a description to a specific input. - A string containing an interpolation block must not exceed 1 MB. - The string inside an interpolation block must not exceed 1 KB. @@ -54,6 +57,7 @@ spec: default: 'test-user' flags: default: null + description: 'Sample description of the `flags` input detail.' --- # The pipeline configuration would follow... @@ -63,7 +67,7 @@ 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. +- `flags` is optional. If not defined, it has no value. The optional description should give details about the input. ## Set input parameter values with `include:inputs` @@ -85,8 +89,6 @@ include: 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. ### Use `include:inputs` with multiple files diff --git a/lib/gitlab/ci/config/header/input.rb b/lib/gitlab/ci/config/header/input.rb index 76a89a3080eae3b547fa205bc539e887e2089703..ed293cb6f4b6ccdec176cd7f90c6a5ed71327ec2 100644 --- a/lib/gitlab/ci/config/header/input.rb +++ b/lib/gitlab/ci/config/header/input.rb @@ -11,13 +11,14 @@ class Input < ::Gitlab::Config::Entry::Node include ::Gitlab::Config::Entry::Validatable include ::Gitlab::Config::Entry::Attributable - attributes :default, :type, prefix: :input + attributes :default, :description, :type, prefix: :input validations do - validates :config, type: Hash, allowed_keys: [:default, :type] + validates :config, type: Hash, allowed_keys: [:default, :type, :description] validates :key, alphanumeric: true validates :input_default, alphanumeric: true, allow_nil: true validates :input_type, allow_nil: true, allowed_values: Interpolation::Inputs.input_types + validates :input_description, alphanumeric: true, allow_nil: true end end end diff --git a/spec/lib/gitlab/ci/config/header/input_spec.rb b/spec/lib/gitlab/ci/config/header/input_spec.rb index b5155dff6e8aef2823c1fb215887bb57c8c8dece..b4e02c2b005012f743ddac10ae447fecdfc56d59 100644 --- a/spec/lib/gitlab/ci/config/header/input_spec.rb +++ b/spec/lib/gitlab/ci/config/header/input_spec.rb @@ -46,6 +46,12 @@ it_behaves_like 'a valid input' end + context 'when has a description value' do + let(:input_hash) { { description: 'bar' } } + + it_behaves_like 'a valid input' + end + context 'when is a required input' do let(:input_hash) { nil } diff --git a/spec/services/ci/create_pipeline_service_spec.rb b/spec/services/ci/create_pipeline_service_spec.rb index a28dd9e7a556335c5055d1165455b557c5d0e033..11f9708f9f3d536a64297997d3b84ed29c118fe6 100644 --- a/spec/services/ci/create_pipeline_service_spec.rb +++ b/spec/services/ci/create_pipeline_service_spec.rb @@ -1953,6 +1953,32 @@ def previous_commit_sha_from_ref(ref) expect(pipeline.statuses.count).to eq 2 expect(pipeline.statuses.map(&:name)).to match_array %w[test-1 test-my-job] end + + context 'when inputs have a description' do + let(:template) do + <<~YAML + spec: + inputs: + stage: + suffix: + default: my-job + description: description + --- + test-$[[ inputs.suffix ]]: + stage: $[[ inputs.stage ]] + script: run tests + YAML + end + + it 'creates a pipeline' do + response = execute_service(save_on_errors: true) + + pipeline = response.payload + + expect(pipeline).to be_persisted + expect(pipeline.yaml_errors).to be_blank + end + end end context 'when interpolation is invalid' do