Table of contents

🎛️ GitLab CI/CD: Inputs Are Typed Parameters, Variables Are Not

You wrote a reusable CI template. Teams customize it with variables, a typo in a variable name silently falls back to nothing, and the failure shows up twenty minutes later in a job log.

GitLab has a stricter mechanism for this: spec:inputs.

The discovery: Inputs are parameters with a contract

Inputs are defined in the configuration file’s header, followed by a --- document separator, and used with the $[[ inputs.name ]] syntax:

spec:
  inputs:
    environment:
      options: ['test', 'staging', 'production']
    concurrency:
      type: number
      default: 1
---
deploy:
  script:
    - ./deploy.sh $[[ inputs.environment ]] $[[ inputs.concurrency ]]

An input without a default is mandatory. Types can be string (the default), array, number or boolean, and you can restrict values with options or a regex.

The caller passes values with include:inputs:

include:
  - local: 'deploy.yml'
    inputs:
      environment: 'staging'
      concurrency: 2

Anything that violates the contract, such as an unlisted option or a wrongly typed value, is rejected when the pipeline is created, not halfway through a job.

Inputs vs. variables

According to the GitLab documentation:

  • Inputs are interpolated when the pipeline is created and remain fixed for the whole run. They are meant for customizing reusable configuration, with type checking and validation.
  • CI/CD variables exist at job runtime and can be defined at several levels, generated or modified during the pipeline.

If the value must be known to decide what the pipeline looks like, use an input. If a job needs it in its environment, use a variable.

The important nuance: Strings and quotes

Inputs are substituted into the configuration text, and that has consequences. The troubleshooting section of the documentation shows one example: in a rules:if expression, an input value inserted unquoted can produce an invalid expression.

rules:
  - if: $CI_COMMIT_REF_NAME == "$[[ inputs.branch ]]"

Quote the interpolated value when the expression expects a string.

Two more details:

  • Inputs are only available in the file that defines the spec. To use a value in another included file, pass it explicitly.
  • Don’t use a !reference tag as an input value, because inputs are interpolated before reference tags are resolved.

The takeaway ☕

When you publish reusable CI configuration, give it a typed interface. Defaults, options and regexes turn a mysterious runtime failure into a clear error at pipeline creation.

Variables are for the job’s environment. Inputs are for the shape of your pipeline.

References

Related articles