Skip to main content

GitLab CI/CD Vs Job Inputs

Summary: GitLab has two similarly-named, similarly-shaped "inputs" systems that operate at different times. CI/CD (config) inputs fill placeholders in before a pipeline is built and can change which jobs exist. Job inputs fill placeholders in for one already-existing job, right when it's run or retried.

At a glance​

QuestionAnswer
What is it?Two typed, validated placeholder-filling systems in GitLab CI/CD YAML
Why does it matter?Picking the wrong one fails silently in scope — e.g. job inputs can never control which jobs exist
When do I use it?CI/CD inputs for reusable templates or whole-pipeline options; job inputs for letting someone tweak one job before running it manually

How it works​

  • Interpolation = replacing a placeholder with a real value (like mail-merge's [Name]).
  • CI/CD (config) inputs — defined in a file's spec:inputs: header, referenced with $[[ inputs.name ]]. Resolved before the pipeline is built, so they can control which jobs exist, their stage, or what gets included. Values lock for the whole pipeline once it starts. No default given means the value is mandatory.
  • Job inputs — defined with inputs: directly on one job, referenced with ${{ job.inputs.name }}. Resolved when that one job is run or retried. Every job input must have a default. Usable only inside that job's script, before_script, after_script, artifacts, cache, image, services — never in job name, stage, rules, or include, since those resolve earlier.
  • Both support string, number, boolean, array types, plus options (restrict to a list) and regex (pattern match) for validation.

Example​

spec:
  inputs:
    environment:
      options: ['staging', 'production']
      default: 'staging'
---

deploy:
  inputs:
    replicas:
      type: number
      default: 3
  script:
    - ./deploy.sh --env $[[ inputs.environment ]] --replicas ${{ job.inputs.replicas }}

environment is chosen on the "Run pipeline" form before the pipeline exists. replicas is chosen on deploy's own manual-run form, only when that job runs.

Remember​

  • CI/CD inputs settle the pipeline's shape before it exists; job inputs tweak one already-existing job.
  • Job inputs always need a default; CI/CD inputs don't (no default = mandatory).
  • Syntax differs: $[[ inputs.x ]] (CI/CD) vs ${{ job.inputs.x }} (job).
  • In the UI: CI/CD inputs appear on "Run pipeline"; job inputs appear when clicking a manual job's name (not the play icon) or "Retry job with modified values."

Sources​