1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
---
stage: Verify
group: Pipeline Authoring
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Define inputs for configuration added with `include` **(FREE ALL BETA)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a Beta feature.
FLAG:
`spec` and `inputs` are experimental [Open Beta features](../../policy/experiment-beta-support.md#beta)
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:inputs`](#set-input-parameter-values-with-includeinputs)
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.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, but before the configuration is merged with the contents of the `.gitlab-ci.yml`.
```yaml
spec:
inputs:
environment:
job-stage:
---
scan-website:
stage: $[[ inputs.job-stage ]]
script: ./scan-website $[[ inputs.environment ]]
```
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.
- A string containing an interpolation block must not exceed 1 MB.
- The string inside an interpolation block must not exceed 1 KB.
For example, a `custom_configuration.yml`:
```yaml
spec:
inputs:
website:
user:
default: 'test-user'
flags:
default: null
---
# 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.
## Set input parameter values with `include:inputs`
> `include:with` [renamed to `include:inputs`](https://gitlab.com/gitlab-org/gitlab/-/issues/406780) in GitLab 16.0.
Use `include:inputs` to set the values for the parameters when the included configuration
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: 'custom_configuration.yml'
inputs:
website: "My website"
```
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
`inputs` must be specified separately for each included file. For example:
```yaml
include:
- component: gitlab.com/org/my-component@1.0
inputs:
stage: my-stage
- local: path/to/file.yml
inputs:
stage: my-stage
```
You can also include the same file multiple times, with different inputs.
For example:
```yaml
include:
- local: path/to/my-super-linter.yml
inputs:
type: docs
job-name: lint-docs
lint-path: "doc/"
- local: path/to/my-super-linter.yml
inputs:
type: yaml
job-name: lint-yaml
lint-path: "data/yaml/"
```
## Specify functions to manipulate input values
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409462) in GitLab 16.3.
You can specify predefined functions in the interpolation block to manipulate the input value.
The format supported is the following:
```yaml
$[[ input.input-id | <function1> | <function2> | ... <functionN> ]]
```
Details:
- Only [predefined interpolation functions](#predefined-interpolation-functions) are permitted.
- A maximum of 3 functions may be specified in a single interpolation block.
- The functions are executed in the sequence they are specified.
```yaml
spec:
inputs:
test:
default: '0123456789'
---
test-job:
script: echo $[[ inputs.test | truncate(1,3) ]]
```
In this example:
- The function [`truncate`](#truncate) applies to the value of `inputs.test`.
- Assuming the value of `inputs.test` is `0123456789`, then the output of `script` would be `echo 123`.
### Predefined interpolation functions
#### `truncate`
Use `truncate` to shorten the interpolated value. For example:
- `truncate(<offset>,<length>)`
| Name | Type | Description |
| ---- | ---- | ----------- |
| `offset` | Integer | Number of characters to offset by. |
| `length` | Integer | Number of characters to return after the offset. |
Example:
```yaml
$[[ inputs.test | truncate(3,5) ]]
```
Assuming the value of `inputs.test` is `0123456789`, then the output would be `34567`.
|
