Help us learn about your current experience with the documentation. Take the survey.

CI/CD 输入

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用 CI/CD 输入可增强 CI/CD 配置的灵活性。输入和 CI/CD 变量
用法相似，但优势不同：

输入为可重用模板提供类型化参数，并在流水线创建时内置验证。
若需在流水线运行时定义具体值，请使用输入而非 CI/CD 变量。
CI/CD 变量支持多层级定义的灵活值，但可在流水线执行期间修改。
适用于需要在作业运行环境中访问的值。
您还可将预定义变量与 rules 结合使用，
实现动态流水线配置。

CI/CD 输入与变量对比

输入：

用途：在 CI 配置（模板、组件或 .gitlab-ci.yml）中定义，并在触发流水线时赋值，
允许使用者自定义可重用 CI 配置。
修改：在流水线初始化传递后，输入值在 CI/CD 配置中插值，并在整个流水线运行期间保持固定。
作用域：仅在定义文件中可用（.gitlab-ci.yml 或被 include 的文件）。
可通过 include:inputs 显式传递给其他文件，或通过 trigger:inputs 传递给流水线。
验证：提供强大的验证能力，包括类型检查、正则表达式、预定义选项列表及用户友好的描述。

CI/CD 变量：

用途：可在作业执行期间设置为环境变量，并在流水线各部分用于作业间数据传递。
修改：可通过 dotenv 工件、条件规则或作业脚本在流水线执行期间动态生成或修改。
作用域：可全局定义（影响所有作业）、作业级别定义（仅影响特定作业），
或通过 GitLab UI 为整个项目/组定义。
验证：简单的键值对，内置验证有限，但可通过 GitLab UI 为项目变量添加部分控制。

使用 `spec:inputs` 定义输入参数

在 CI/CD 配置的头部中使用 spec:inputs 定义可传递给配置文件的输入参数。

在头部区域外使用 $[[ inputs.input-id ]] 插值格式声明输入的使用位置。

例如：

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

此示例中，输入为 job-stage 和 environment。

使用 spec:inputs 时：

若未指定 default，输入为必填项。
输入在流水线创建时获取配置时进行求值和填充。
包含输入的字符串必须小于 1 MB。
输入内部的字符串必须小于 1 KB。
输入可使用 CI/CD 变量，但受与 include 关键字相同的变量限制。

当您执行以下操作时，需设置输入值：

使用此配置文件触发新流水线。
通过除 include 外的任何方法配置新流水线时，都应设置默认值。
否则若新流水线自动触发（包括合并请求流水线、分支流水线、标签流水线），流水线可能启动失败。
将配置包含到您的流水线中。
所有必填输入必须添加到 include:inputs 部分，并在每次包含配置时使用。

输入配置

通过以下方式配置输入：

spec:inputs:default：定义未指定时的默认值。
指定默认值后，输入不再为必填项。
spec:inputs:description：为特定输入添加描述。
描述不影响输入，但可帮助理解输入详情或预期值。
spec:inputs:options：指定输入的允许值列表。
spec:inputs:regex：指定输入必须匹配的正则表达式。
spec:inputs:type：强制指定输入类型，可为 string（未指定时默认）、array、number 或 boolean。

每个 CI/CD 配置文件可定义多个输入，每个输入可包含多个配置参数。

例如，在名为 scan-website-job.yml 的文件中：

spec:
  inputs:
    job-prefix:     # 必填字符串输入
      description: "定义作业名称的前缀"
    job-stage:      # 可选字符串输入，未提供时默认值为 test
      default: test
    environment:    # 必填输入，必须匹配选项之一
      options: ['test', 'staging', 'production']
    concurrency:
      type: number  # 可选数字输入，未提供时默认值为 1
      default: 1
    version:        # 必填字符串输入，必须匹配正则表达式
      type: string
      regex: ^v\d\.\d+(\.\d+)$
    export_results: # 可选布尔输入，未提供时默认值为 true
      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

此示例中：

job-prefix 是必填字符串输入，必须定义。
job-stage 是可选的。若未定义，值为 test。
environment 是必填字符串输入，必须匹配定义的选项之一。
concurrency 是可选数字输入。未指定时默认为 1。
version 是必填字符串输入，必须匹配指定的正则表达式。
export_results 是可选布尔输入。未指定时默认为 true。

输入类型

可通过可选的 spec:inputs:type 关键字指定输入必须使用特定类型。

输入类型包括：

array
boolean
number
string（未指定时默认）

当输入替换 CI/CD 配置中的整个 YAML 值时，按其指定类型插值到配置中。例如：

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

当输入作为更大字符串的一部分插入 YAML 值时，始终作为字符串插值。例如：

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

test_job:
  script: curl "https://gitlab.com:$[[ inputs.port ]]"

数组类型

数组类型项的内容可以是任何有效的 YAML 映射、序列或标量。无法使用 !reference 等更复杂的 YAML 功能。
在字符串中使用数组输入的值时（例如 script: 部分中的 echo "My rules: $[[ inputs.rules-config ]]"），
可能会出现意外结果。数组输入会转换为字符串表示形式，对于复杂 YAML 结构（如映射）可能不符合预期。

spec:
  inputs:
    rules-config:
      type: array
      default:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
          when: manual
        - if: $CI_PIPELINE_SOURCE == "schedule"
---

test_job:
  rules: $[[ inputs.rules-config ]]
  script: ls

手动传递输入时（如下场景），数组必须格式化为 JSON，例如 ["array-input-1", "array-input-2"]：

多行输入字符串值

输入支持不同值类型。可通过以下格式传递多行字符串值：

spec:
  inputs:
    closed_message:
      description: 宣布问题关闭时的消息。
      default: 'Hi {{author}} :wave:,

        根据非活跃问题的策略，此问题现在将被关闭。

        若此问题需要进一步关注，请重新打开此问题。'
---

设置输入值

为使用 `include` 添加的配置设置

使用 include:inputs 为包含的配置设置输入值，包括：

CI/CD 组件
自定义 CI/CD 模板
任何通过 include 添加的配置。

例如，为输入配置示例中的 scan-website-job.yml 包含并设置输入值：

include:
  - local: 'scan-website-job.yml'
    inputs:
      job-prefix: 'some-service-'
      environment: 'staging'
      concurrency: 2
      version: 'v1.3.2'
      export_results: false

此示例中，包含配置的输入如下：

输入	值	说明
`job-prefix`	`some-service-`	必须显式定义。
`job-stage`	`test`	未在 `include:inputs` 中定义，值来自包含配置中的 `spec:inputs:default`。
`environment`	`staging`	必须显式定义，且必须匹配包含配置中 `spec:inputs:options` 的值之一。
`concurrency`	`2`	必须为数值以匹配包含配置中 `spec:inputs:type` 设置的 `number`。覆盖默认值。
`version`	`v1.3.2`	必须显式定义，且必须匹配包含配置中 `spec:inputs:regex` 的正则表达式。
`export_results`	`false`	必须为 `true` 或 `false` 以匹配包含配置中 `spec:inputs:type` 设置的 `boolean`。覆盖默认值。

多个 `include` 条目

必须为每个包含条目单独指定输入。例如：

include:
  - component: $CI_SERVER_FQDN/the-namespace/the-project/the-component@1.0
    inputs:
      stage: my-stage
  - local: path/to/file.yml
    inputs:
      stage: my-stage

为流水线设置输入值

输入相较于变量的优势包括类型检查、验证和明确契约。意外输入会被拒绝。
流水线输入必须在主 .gitlab-ci.yml 文件的 spec:inputs 头部中定义。
无法使用包含文件中定义的输入进行流水线级配置。

在 GitLab 17.7
及更高版本中，推荐使用流水线输入而非传递流水线变量。
为增强安全性，使用输入时应禁用流水线变量。

定义流水线输入时，始终应设置默认值。
否则若新流水线自动触发（例如合并请求流水线、分支流水线、标签流水线），流水线可能启动失败。
无法手动设置合并请求流水线的输入，因此若任何输入缺少默认值，流水线创建将失败。

可通过以下方式设置输入值：

单个流水线最多可接收 20 个输入。

欢迎在此问题中提供反馈。

若下游流水线的配置文件使用 spec:inputs，
可将输入传递给下游流水线。

例如，使用 trigger:inputs：

trigger-job:
  trigger:
    strategy: mirror
    include:
      - local: path/to/child-pipeline.yml
        inputs:
          job-name: "defined"
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

trigger-job:
  trigger:
    strategy: mirror
    project: project-group/my-downstream-project
    inputs:
      job-name: "defined"
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

指定操作输入值的函数

可在插值块中指定预定义函数来操作输入值。支持的格式如下：

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

使用函数时：

仅允许使用预定义插值函数。
单个插值块最多可指定 3 个函数。
函数按指定顺序执行。

spec:
  inputs:
    test:
      default: 'test $MY_VAR'
---

test-job:
  script: echo $[[ inputs.test | expand_vars | truncate(5,8) ]]

此示例中，假设输入使用默认值且 $MY_VAR 是值为 my value 的未屏蔽项目变量：

首先，函数 expand_vars 将值扩展为 test my value。
然后 truncate 对 test my value 应用偏移量 5 和长度 8。
script 的输出为 echo my value。

预定义插值函数

`expand_vars`

使用 expand_vars 扩展输入值中的 CI/CD 变量。
仅可扩展您能与 include 关键字一起使用
且未屏蔽的变量。
不支持嵌套变量扩展。

示例：

spec:
  inputs:
    test:
      default: 'test $MY_VAR'
---

test-job:
  script: echo $[[ inputs.test | expand_vars ]]

此示例中，若 $MY_VAR 是值为 my value 的未屏蔽变量（在作业日志中暴露），
则输入将扩展为 test my value。

`truncate`

使用 truncate 缩短插值后的值。例如：

truncate(<offset>,<length>)

名称	类型	说明
`offset`	Integer	偏移的字符数。
`length`	Integer	偏移后返回的字符数。

示例：

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

假设 inputs.test 的值为 0123456789，则输出为 34567。

故障排除

使用 `inputs` 时的 YAML 语法错误

rules:if 中的 CI/CD 变量表达式
期望 CI/CD 变量与字符串的比较，否则可能返回多种语法错误。

必须确保输入值插入配置后表达式格式正确，这可能需要额外添加引号。

例如：

spec:
  inputs:
    branch:
      default: $CI_DEFAULT_BRANCH
---

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

此示例中：

使用 include: inputs: branch: $CI_DEFAULT_BRANCH 是有效的。if: 子句求值为 if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH，这是有效的变量表达式。
使用 include: inputs: branch: main 是无效的。if: 子句求值为 if: $CI_COMMIT_REF_NAME == main，这是无效的，因为 main 是字符串但未加引号。

或者，添加引号可解决部分变量表达式问题。例如：

spec:
  inputs:
    environment:
      default: "$ENVIRONMENT"
---

$[[ inputs.environment | expand_vars ]] job:
  script: echo
  rules:
    - if: '"$[[ inputs.environment | expand_vars ]]" == "production"'

此示例中，对输入块和整个变量表达式加引号可确保输入求值后 if: 语法有效。
表达式中的内部和外部引号不能是相同字符。可对内部引号使用 "，外部引号使用 '，或反之。
另一方面，作业名称无需任何引号。