CI/CD 输入

使用 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 ]] 插值格式来声明在哪里使用这些输入。

例如：

yaml
1spec:
2  inputs:
3    job-stage:
4      default: test
5    environment:
6      default: production
7---
8scan-website:
9  stage: $[[ inputs.job-stage ]]
10  script: ./scan-website $[[ inputs.environment ]]

在这个例子中，输入是 job-stage 和 environment。

使用 spec:inputs 时：

• 如果未指定 default，则输入是必填的。
• 输入在流水线创建期间获取配置时被评估和填充。
• 包含输入的字符串必须小于 1 MB。
• 输入内部的字符串必须小于 1 KB。
• 输入可以使用 CI/CD 变量，但具有与 include 关键字相同的变量限制。
• 如果定义 spec:inputs 的文件也包含作业定义，请在头部之后添加一个 YAML 文档分隔符 (---)。

然后，在以下情况下为输入设置值：

• 运行新流水线 使用此配置文件。当使用除 include 以外的任何方法配置新流水线时，你应该始终设置默认值。否则，如果新流水线自动触发，流水线可能无法启动，包括：
  • 合并请求流水线
  • 分支流水线
  • 标签流水线
• 将配置包含在流水线中。任何必填的输入都必须添加到 include:inputs 部分，并在每次包含该配置时使用。

输入配置#

要配置输入，请使用：

• spec:inputs:default 为未指定的输入定义默认值。当你指定默认值时，输入不再是必填的。
• spec:inputs:description 为特定输入提供描述。该描述不会影响输入，但可以帮助人们理解输入的详细信息或预期值。
• spec:inputs:options 为输入指定允许值的列表。
• spec:inputs:regex 指定输入必须匹配的正则表达式。
• spec:inputs:type 强制指定输入类型，可以是 string（未指定时的默认值）、array、number 或 boolean。
• spec:inputs:rules 根据其他输入的值定义条件 options 和 default 值。

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

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

yaml
1spec:
2  inputs:
3    job-prefix:     # 必填的字符串输入
4      description: "为作业名称定义一个前缀"
5    job-stage:      # 可选的字符串输入，未提供时使用默认值
6      default: test
7    environment:    # 必填输入，必须匹配其中一个选项
8      options: ['test', 'staging', 'production']
9    concurrency:
10      type: number  # 可选的数字输入，未提供时使用默认值
11      default: 1
12    version:        # 必填的字符串输入，必须匹配正则表达式
13      type: string
14      regex: ^v\d\.\d+(\.\d+)$
15    export_results: # 可选的布尔输入，未提供时使用默认值
16      type: boolean
17      default: true
18---
19
20"$[[ inputs.job-prefix ]]-scan-website":
21  stage: $[[ inputs.job-stage ]]
22  script:
23    - echo "扫描网站 -e $[[ inputs.environment ]] -c $[[ inputs.concurrency ]] -v $[[ inputs.version ]]"
24    - if $[[ inputs.export_results ]]; then echo "导出结果"; fi

在这个例子中：

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

输入类型#

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

输入类型有：

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

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

yaml
1spec:
2  inputs:
3    array_input:
4      type: array
5    boolean_input:
6      type: boolean
7    number_input:
8      type: number
9    string_input:
10      type: string
11---
12
13test_job:
14  allow_failure: $[[ inputs.boolean_input ]]
15  needs: $[[ inputs.array_input ]]
16  parallel: $[[ inputs.number_input ]]
17  script: $[[ inputs.string_input ]]

当输入作为较大字符串的一部分插入到 YAML 值中时，输入始终以字符串形式插值。例如：

yaml
1spec:
2  inputs:
3    port:
4      type: number
5---
6
7test_job:
8  script: curl "https://gitlab.com:$[[ inputs.port ]]"

数组类型#

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

yaml
1spec:
2  inputs:
3    rules-config:
4      type: array
5      default:
6        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
7          when: manual
8        - if: $CI_PIPELINE_SOURCE == "schedule"
9---
10
11test_job:
12  rules: $[[ inputs.rules-config ]]
13  script: ls

当手动传递输入时，数组输入必须格式化为 JSON，例如 ["array-input-1", "array-input-2"]，用于：

• 手动运行流水线。
• 流水线触发器 API。
• 流水线 API。
• Git 推送选项
• 流水线计划

带选项的数组输入#

你可以定义一个选项列表来限制数组输入的允许值。当你手动运行流水线时，UI 会显示一个多选下拉菜单，而不是文本字段。例如：

yaml
1spec:
2  inputs:
3    runner_tags:
4      type: array
5      default: ["docker"]
6      options:
7        - docker
8        - linux
9        - gpu
10        - macos
11---
12
13test:
14  script:
15    - run_tests.sh
16  tags: $[[ inputs.runner_tags ]]

如果数组输入中的任何值与列出的选项不匹配，流水线将无法启动。

访问单个数组元素#

使用带索引号的方括号表示法来访问数组输入的单个元素。数组项按照它们在 YAML 数组中定义的顺序进行索引，使用正数，[0] 索引项是数组中的第一项。

例如：

yaml
1spec:
2  inputs:
3    supported_versions:
4      type: array
5      default:
6        - '2.0'
7        - '1.0'
8        - '0.1'
9---
10
11job:
12  script:
13    # 输出：'最新版本是 2.0'
14    - echo '最新版本是 $[[ inputs.supported_versions[0] ]]'

你可以将数组索引与点表示法链接起来以访问嵌套值：

yaml
1spec:
2  inputs:
3    servers:
4      type: array
5      default:
6        - host: server1.example.com
7          port: 8080
8---
9
10job:
11  script:
12    - curl "https://$[[ inputs.servers[0].host ]]:$[[ inputs.servers[0].port ]]"

对于多维数组，连续使用多个索引。例如，对于二维数组，你可以使用 [0][1]：

yaml
1spec:
2  inputs:
3    matrix:
4      type: array
5      default:
6        - ['a', 'b']
7        - ['c', 'd']
8---
9
10job:
11  script:
12    # 输出：'b'
13    - echo $[[ inputs.matrix[0][1] ]]

每个段最多可以链接 5 个索引，例如 arr[0][1][2][3][4]。

多行输入字符串值#

输入支持不同的值类型。你可以使用以下格式传递多行字符串值：

yaml
1spec:
2  inputs:
3    closed_message:
4      description: 议题关闭时发布的消息。
5      default: '你好 {{author}} :wave:,
6
7        根据非活跃议题的策略，此议题现在将被关闭。
8
9        如果此议题需要进一步关注，请重新打开此议题。'
10---

使用 spec:inputs:rules 定义条件输入选项#

使用 spec:inputs:rules 根据其他输入的值，为输入定义不同的 options 和 default 值。当一个输入应该根据其他输入提供的上下文而具有不同的允许值时，你可以使用此配置。

rules 列表中的每个规则可以包含：

• if：一个表达式，检查一个或多个输入的值，以确定此规则何时适用。使用与 $[[ inputs.input-id ]] 插值 相同的语法。
• options：当此规则匹配时，输入的允许值列表。
• default：当此规则匹配时使用的默认值。

规则按顺序评估。第一个具有匹配 if 条件的规则将被使用。没有 if 条件的最后一个规则作为其他规则都不匹配时的回退。

例如，要定义根据云提供商和环境而变化的实例类型：

yaml
1spec:
2  inputs:
3    cloud_provider:
4      options: ['aws', 'gcp', 'azure']
5      default: 'aws'
6      description: '云提供商'
7
8    environment:
9      options: ['development', 'staging', 'production']
10      default: 'development'
11      description: '目标环境'
12
13    instance_type:
14      description: '虚拟机实例类型'
15      rules:
16        - if: $[[ inputs.cloud_provider ]] == 'aws' && $[[ inputs.environment ]] == 'development'
17          options: ['t3.micro', 't3.small']
18          default: 't3.micro'
19        - if: $[[ inputs.cloud_provider ]] == 'aws' && $[[ inputs.environment ]] == 'production'
20          options: ['t3.xlarge', 't3.2xlarge', 'm5.xlarge']
21          default: 't3.xlarge'
22        - if: $[[ inputs.cloud_provider ]] == 'gcp'
23          options: ['e2-micro', 'e2-small', 'e2-standard-4']
24          default: 'e2-micro'
25        - if: $[[ inputs.cloud_provider ]] == 'azure'
26          options: ['Standard_B1s', 'Standard_B2s', 'Standard_D2s_v3']
27          default: 'Standard_B1s'
28        - options: ['small', 'medium', 'large']  # 任何其他情况的回退
29          default: 'small'
30---
31
32deploy:
33  script: |
34    echo "部署到 $[[ inputs.cloud_provider ]]"
35    echo "环境：$[[ inputs.environment ]]"
36    echo "实例：$[[ inputs.instance_type ]]"

在这个例子中：

• 当 cloud_provider 为 aws 且 environment 为 development 时，用户可以从 t3.micro 或 t3.small 实例类型中选择，默认值为 t3.micro。
• 当 cloud_provider 为 aws 且 environment 为 production 时，可用的实例类型不同（t3.xlarge、t3.2xlarge、m5.xlarge）。
• 当 cloud_provider 为 gcp 时，无论环境如何，都可以使用 GCP 特定的实例类型。
• 如果所有条件都不匹配，回退规则提供通用的尺寸选项。

你还可以使用 ||（或）运算符来匹配多个条件。例如：

yaml
1spec:
2  inputs:
3    deployment_type:
4      options: ['canary', 'blue-green', 'rolling', 'recreate']
5      default: 'rolling'
6
7    requires_approval:
8      description: '部署是否需要手动批准'
9      rules:
10        - if: $[[ inputs.deployment_type ]] == 'canary' || $[[ inputs.deployment_type ]] == 'blue-green'
11          options: ['true']
12          default: 'true'
13        - options: ['true', 'false']
14          default: 'false'
15---
16
17deploy:
18  script: echo "使用 $[[ inputs.deployment_type ]] 策略部署"

在这个例子中，当 deployment_type 为 canary 或 blue-green 时，requires_approval 输入被设置为 true。在所有其他情况下，默认值为 false，并且 true 或 false 都是允许的选项。

使用 default: null 允许用户输入值#

使用带有 default: null 且不带 options 的 spec:inputs:rules，允许用户为输入输入自己的值。这对于工作流特定的值（如环境名称或测试配置）非常有用。

例如：

yaml
1spec:
2  inputs:
3    deployment_type:
4      options: ['standard', 'custom']
5      default: 'standard'
6
7    custom_config:
8      description: '自定义配置值'
9      rules:
10        - if: $[[ inputs.deployment_type ]] == 'custom'
11          default: null
12---
13
14deploy:
15  script: echo "配置：$[[ inputs.custom_config ]]"

在这个例子中，当 deployment_type 为 custom 时，custom_config 输入会显示在运行流水线页面上，用户必须为该输入输入一个值。

在 spec:inputs:rules 中使用布尔输入#

你可以在规则条件中使用布尔输入。布尔值可以使用布尔字面量（true/false）进行比较：

yaml
1spec:
2  inputs:
3    publish:
4      type: boolean
5      default: true
6
7    publish_stage:
8      rules:
9        - if: $[[ inputs.publish ]] == true
10          default: 'publish'
11        - if: $[[ inputs.publish ]] == false
12          default: 'test'
13---
14
15job:
16  stage: $[[ inputs.publish_stage ]]
17  script: echo "发布状态为 $[[ inputs.publish ]]"

在这个例子中，当 publish 为 true 时，publish_stage 默认为 publish。当 publish 为 false 时，它默认为 test。

设置输入值#

你可以在流水线配置中或触发流水线时设置输入值。

流水线启动后，你无法获取任何已使用的输入值。如果某个值可以安全公开，你可以在作业日志中输出该值以供将来参考，或者将其保存在产物中。

对于通过 include 添加的配置#

当包含的配置被添加到流水线时，使用 include:inputs 为输入设置值，包括：

• CI/CD 组件
• 通过 include 添加的任何其他配置。

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

yaml
1include:
2  - local: 'scan-website-job.yml'
3    inputs:
4      job-prefix: 'some-service-'
5      environment: 'staging'
6      concurrency: 2
7      version: 'v1.3.2'
8      export_results: false

在这个例子中，包含的配置的输入为：

对于多个 include 条目#

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

yaml
1include:
2  - component: $CI_SERVER_FQDN/the-namespace/the-project/the-component@1.0
3    inputs:
4      stage: my-stage
5  - local: path/to/file.yml
6    inputs:
7      stage: my-stage

对于流水线#

输入提供了优于变量的优势，包括类型检查、验证和清晰的契约。意外的输入会被拒绝。流水线的输入必须在主 .gitlab-ci.yml 文件的 spec:inputs 头部 中定义。你不能使用包含文件中定义的输入进行流水线级别的配置。

在为流水线定义输入时，你应该始终设置默认值。如果任何输入缺少默认值，流水线在自动触发时会失败。例如，合并请求流水线可以针对合并请求源分支的更改触发。你无法为合并请求流水线手动设置输入，因此如果任何输入缺少默认值，流水线将失败。这也可能发生在分支流水线、标签流水线和其他自动触发的流水线上。

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

• 下游流水线
• 手动运行流水线。
• 流水线触发器 API
• 流水线 API
• Git 推送选项
• 流水线计划
• trigger 关键字

一个流水线最多可以接受 20 个输入。

你可以将输入传递给下游流水线，前提是下游流水线的配置文件使用了 spec:inputs。

例如，使用 trigger:inputs：

yaml
1trigger-job:
2  trigger:
3    strategy: mirror
4    include:
5      - local: path/to/child-pipeline.yml
6        inputs:
7          job-name: "defined"
8  rules:
9    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

yaml
1trigger-job:
2  trigger:
3    strategy: mirror
4    project: project-group/my-downstream-project
5    inputs:
6      job-name: "defined"
7  rules:
8    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

在外部文件中定义流水线输入#

你可以通过在外部文件中定义流水线输入定义，并使用 spec:include 将它们包含到项目的流水线配置中，从而在多个 CI/CD 配置中重用这些定义。

创建一个包含输入定义的文件，例如在名为 shared-inputs.yml 的文件中：

yaml
1inputs:
2  environment:
3    description: "部署环境"
4    options: ['staging', 'production']
5  region:
6    default: 'us-east-1'

然后，你可以在 .gitlab-ci.yml 中使用 local 包含这些外部输入：

yaml
1spec:
2  include:
3    - local: /shared-inputs.yml
4---
5
6deploy:
7  script: echo "部署到 $[[ inputs.environment ]] 在 $[[ inputs.region ]] 区域"

如果文件存储在项目之外，你可以使用：

• project 用于另一个极狐GitLab 项目中的文件。使用完整的项目路径，并使用 file 定义文件名。你还可以选择定义 ref 来获取文件。
• remote 用于另一台服务器上的文件。使用文件的完整 URL。

你还可以同时包含多个输入文件，例如：

yaml
1spec:
2  include:
3    - local: /shared-inputs.yml
4    - project: 'my-group/shared-configs'
5      ref: main
6      file: '/ci/common-inputs.yml'
7    - remote: 'https://example.com/ci/shared-inputs.yml'
8---

从外部文件覆盖输入#

输入键在所有包含的文件和内联规范中必须唯一。如果你在多个包含的文件中，或在包含的文件和 .gitlab-ci.yml 配置的 inputs: 部分中定义了相同键的输入，则会返回以下错误：

plaintext
发现重复的输入键：environment。输入键在所有包含的文件和内联规范中必须唯一。

要修复此错误，请确保每个输入键只定义一次，要么在包含的文件中，要么在内联 inputs: 部分中，但不能同时在两者中。

指定用于操作输入值的函数#

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

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

关于函数：

• 只允许使用预定义的插值函数。
• 单个插值块中最多可以指定 3 个函数。
• 函数按照指定的顺序执行。

yaml
1spec:
2  inputs:
3    test:
4      default: 'test $MY_VAR'
5---
6
7test-job:
8  script: echo $[[ inputs.test | expand_vars | truncate(5,8) ]]

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

1. 首先，函数 expand_vars 将值扩展为 test my value。
2. 然后，truncate 应用于 test my value，字符偏移量为 5，长度为 8。
3. script 的输出将是 echo my value。

预定义的插值函数#

expand_vars#

使用 expand_vars 扩展输入值中的 CI/CD 变量。

只有可以与 include 关键字一起使用且未掩码的变量才能被扩展。不支持嵌套变量扩展。

示例：

yaml
1spec:
2  inputs:
3    test:
4      default: 'test $MY_VAR'
5---
6
7test-job:
8  script: echo $[[ inputs.test | expand_vars ]]

在此示例中，如果 $MY_VAR 未掩码（在作业日志中暴露）且值为 my value，则输入将扩展为 test my value。

truncate#

使用 truncate 缩短插值。例如：

• truncate(<offset>,<length>)

示例：

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

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

posix_escape#

使用 posix_escape 转义输入值中的任何 POSIX Bourne shell 控制或元字符。posix_escape 通过在输入中相关字符前插入 \ 来转义字符。

示例：

yaml
1spec:
2  inputs:
3    test:
4      default: |
5        A string with single ' and double " quotes and   blanks
6---
7
8test-job:
9  script: printf '%s\n' $[[ inputs.test | posix_escape ]]

在此示例中，posix_escape 转义了可能是 shell 控制或元字符的字符：

console
$ printf '%s\n' A\ string\ with\ single\ \'\ and\ double\ \"\ quotes\ and\ \ \ blanks
A string with single ' and double " quotes and   blanks

转义后的输入保留了提供的特殊字符和间距。

posix_escape 尽力保留输入值，但某些字符组合仍可能导致意外结果。即使使用 posix_escape，仍可能出现以下情况：

• 字符串中包含的 Shell 代码可能会被执行。
• 单引号或双引号可能用于转义任何周围的引号。
• 变量引用可能用于访问受保护的变量。
• 输入或输出重定向可能用于读取或写入本地文件。
• Shell 使用未转义的空格将字符串拆分为多个参数。

出于安全目的，你应该确保输入是可信的。你可以使用：

• spec:input:type number 或 boolean，它们不能包含有问题的字符。
• spec:input:regex 关键字来防止有问题的输入。
• spec:input:options 关键字来定义预定义的输入选项列表。

如果你将 posix_escape 与 expand_vars 结合使用，必须首先设置 expand_vars。否则 posix_escape 会转义变量中的 $，阻止扩展。例如：

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

故障排除#

在 rules 中使用 inputs 时的 YAML 语法错误#

当你使用输入修改 rules:if 表达式时，可能会遇到各种语法错误之一。

这些错误通常与 CI/CD 变量表达式 中字符串的处理方式有关。rules:if 中的表达式期望将 CI/CD 变量与带引号的字符串（' 或 "）或另一个变量进行比较。当在流水线运行时将输入值插入到 rules 配置中时，结果值可能不是带引号的字符串或变量，从而导致错误。

例如，在要包含的配置中：

yaml
1spec:
2  inputs:
3    branch:
4      default: $CI_DEFAULT_BRANCH
5    branch2:
6      default: $CI_DEFAULT_BRANCH
7---
8
9job-name:
10  rules:
11    - if: $CI_COMMIT_REF_NAME == $[[ inputs.branch ]]
12    - if: $CI_COMMIT_REF_NAME == $[[ inputs.branch2 ]]

然后，在主配置文件中：

yaml
include:
  inputs:
    branch: $CI_DEFAULT_BRANCH  # 有效
    branch2: main               # 无效

在此示例中：

• 使用 branch: $CI_DEFAULT_BRANCH 是有效的。if: 子句求值为 if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH，这是一个有效的变量表达式。变量不需要引号。
• 使用 branch2: main 是无效的。if: 子句求值为 if: $CI_COMMIT_REF_NAME == main，这是无效的，因为 main 是一个字符串但没有引号。

要解决此问题，请确保在将输入值插入配置后，表达式保持正确的格式。这可能需要额外的引号字符。例如，为使用字符串值的规则添加引号：

yaml
rules:
  if: $CI_COMMIT_REF_NAME == "$[[ inputs.branch2 ]]"

对于像 expand_vars 这样的插值函数，你可能还需要引用整个 if: 表达式。例如：

yaml
1spec:
2  inputs:
3    environment:
4      default: "$ENVIRONMENT"
5---
6
7$[[ inputs.environment | expand_vars ]] job:
8  script: echo
9  rules:
10    - if: '"$[[ inputs.environment | expand_vars ]]" == "production"'

在此示例中，引用输入和整个 if: 表达式可确保在计算输入后语法有效。当引号嵌套时，内层引号使用 "，外层引号使用 '，或反之。

作业名称不需要引号。