CI/CD inputs

Use CI/CD inputs to increase the flexibility of CI/CD configuration. Inputs and CI/CD variables can be used in similar ways, but have different benefits:

• Inputs provide typed parameters for reusable templates with built-in validation at pipeline creation time. To define specific values when the pipeline runs, use inputs instead of CI/CD variables.
• CI/CD variables offer flexible values that can be defined at multiple levels, but can be modified throughout pipeline execution. Use variables for values that need to be accessible in the job’s runtime environment. You can also use predefined variables with include:rules for dynamic pipeline composition through conditional includes.

CI/CD Inputs and variables comparison

Inputs:

• Purpose: Defined in CI/CD configurations (templates, components, or .gitlab-ci.yml) and assigned values when a pipeline is triggered, allowing consumers to customize reusable CI configurations.
• Modification: Once passed at pipeline initialization, input values are interpolated in the CI/CD configuration and remain fixed for the entire pipeline run.
• Scope: Available only in the file where they are defined, whether in the .gitlab-ci.yml or a file being included. You can pass them explicitly to other files by using include:inputs, or to a pipeline by using trigger:inputs.
• Validation: Provide robust validation capabilities including type checking, regex patterns, predefined option lists, and helpful descriptions for users.

CI/CD Variables:

• Purpose: Values that can be set as environment variables during job execution and in various parts of the pipeline for passing data between jobs.
• Modification: Can be dynamically generated or modified during pipeline execution through dotenv artifacts, conditional rules, or directly in job scripts.
• Scope: Can be defined globally (affecting all jobs), at the job level (affecting only specific jobs), or for the entire project or group through the GitLab UI.
• Validation: Key-value pairs with minimal built-in validation, though you can add some controls through the GitLab UI for project variables.

Define input parameters with spec:inputs

Use spec:inputs in the CI/CD configuration header to define input parameters that can be passed to the configuration file.

Use the $[[ inputs.input-id ]] interpolation format outside the header section to declare where to use the inputs.

For example:

spec:
  inputs:
    job-stage:
      default: test
    environment:
      default: production
---
scan-website:
  stage: $[[ inputs.job-stage ]]
  script: ./scan-website $[[ inputs.environment ]]

In this example, the inputs are job-stage and environment.

You can only use inputs values in the file with the spec section. To use an input value from a different file added with include, pass it to the included file explicitly.

With spec:inputs:

• Inputs are mandatory if default is not specified.
• Inputs are evaluated and populated when the configuration is fetched during pipeline creation.
• A string containing an input must be less than 1 MB.
• A string inside an input must be less than 1 KB.
• Inputs can use CI/CD variables, but have the same variable limitations as the include keyword.
• If the file that defines spec:inputs also contains job definitions, add a YAML document separator (---) after the header.

Then you set the values for the inputs when you:

• Run a new pipeline using this configuration file. You should always set default values when using inputs to configure new pipelines with any method other than include. Otherwise the pipeline could fail to start if a new pipeline triggers automatically, including in:
  • Merge request pipelines
  • Branch pipelines
  • Tag pipelines
• Include the configuration in your pipeline. Any inputs that are mandatory must be added to the include:inputs section, and are used every time the configuration is included.

Input configuration

To configure inputs, use:

• spec:inputs:default to define default values for inputs when not specified. When you specify a default, the inputs are no longer mandatory.
• spec:inputs:description to give a description to a specific input. The description does not affect the input, but can help people understand the input details or expected values.
• spec:inputs:options to specify a list of allowed values for an input.
• spec:inputs:regex to specify a regular expression that the input must match.
• spec:inputs:type to force a specific input type, which can be string (default when not specified), array, number, or boolean.
• spec:inputs:rules to define conditional options and default values based on the values of other inputs.

You can define multiple inputs per CI/CD configuration file, and each input can have multiple configuration parameters.

For example, in a file named scan-website-job.yml:

spec:
  inputs:
    job-prefix:     # Mandatory string input
      description: "Define a prefix for the job name"
    job-stage:      # Optional string input with a default value when not provided
      default: test
    environment:    # Mandatory input that must match one of the options
      options: ['test', 'staging', 'production']
    concurrency:
      type: number  # Optional numeric input with a default value when not provided
      default: 1
    version:        # Mandatory string input that must match the regular expression
      type: string
      regex: ^v\d\.\d+(\.\d+)$
    export_results: # Optional boolean input with a default value when not provided
      type: boolean
      default: true
---

"$[[ inputs.job-prefix ]]-scan-website":
  stage: $[[ inputs.job-stage ]]
  script:
    - echo "scanning website -e $[[ inputs.environment ]] -c $[[ inputs.concurrency ]] -v $[[ inputs.version ]]"
    - if $[[ inputs.export_results ]]; then echo "export results"; fi

In this example:

• job-prefix is a mandatory string input and must be defined.
• job-stage is optional. If not defined, the value is test.
• environment is a mandatory string input that must match one of the defined options.
• concurrency is an optional numeric input. When not specified, it defaults to 1.
• version is a mandatory string input that must match the specified regular expression.
• export_results is an optional boolean input. When not specified, it defaults to true.

Input types

You can specify that an input must use a specific type with the optional spec:inputs:type keyword.

The input types are:

• array
• boolean
• number
• string (default when not specified)

When an input replaces an entire YAML value in the CI/CD configuration, it is interpolated into the configuration as its specified type. For example:

spec:
  inputs:
    array_input:
      type: array
    boolean_input:
      type: boolean
    number_input:
      type: number
    string_input:
      type: string
---

test_job:
  allow_failure: $[[ inputs.boolean_input ]]
  needs: $[[ inputs.array_input ]]
  parallel: $[[ inputs.number_input ]]
  script: $[[ inputs.string_input ]]

When an input is inserted into a YAML value as part of a larger string, the input is always interpolated as a string. For example:

spec:
  inputs:
    port:
      type: number
---

test_job: