• Define input parameters with spec:inputs
• Set input parameter values with include:inputs
  • Use include:inputs with multiple files
• Specify functions to manipulate input values
  • Predefined interpolation functions
    • truncate

Define inputs for configuration added with include

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 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.

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:

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

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:

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:

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:

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

You can specify predefined functions in the interpolation block to manipulate the input value. The format supported is the following:

$[[ input.input-id | <function1> | <function2> | ... <functionN> ]]

Details:

• Only 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.

spec:
  inputs:
    test:
      default: '0123456789'
---

test-job:
  script: echo $[[ inputs.test | truncate(1,3) ]]

In this example:

• The function 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>)

Example:

$[[ inputs.test | truncate(3,5) ]]

Assuming the value of inputs.test is 0123456789, then the output would be 34567.