CI/CD YAML 语法参考

本文档列出了极狐GitLab .gitlab-ci.yml 文件的配置选项。此文件是定义流水线中 CI/CD 作业的地方。

• 如果您已经熟悉 基本的 CI/CD 概念，请尝试通过遵循演示 简单 或 复杂 流水线的教程来创建自己的 .gitlab-ci.yml 文件。
• 有关示例集合，请参见 极狐GitLab CI/CD 示例。
• 要查看企业中使用的大型 .gitlab-ci.yml 文件，请参见 极狐GitLab 的 .gitlab-ci.yml 文件。

编辑 .gitlab-ci.yml 文件时，您可以使用 CI Lint 工具验证它。

如果您正在编辑此页面上的内容，请遵循 关键词文档编写说明。

关键词#

极狐GitLab CI/CD 流水线配置包括：

• 配置流水线行为的 全局关键词：

  关键词	描述
  default	作业关键词的自定义默认值。
  include	从其他 YAML 文件导入配置。
  stages	流水线阶段的名称和顺序。
  workflow	控制运行哪种类型的流水线。

• 头部关键词

  关键词	描述
  spec	为外部配置文件定义规范。

• 使用 作业关键词 配置的 作业：

  关键词	描述
  after_script	覆盖作业完成后执行的一组命令。
  allow_failure	允许作业失败。失败的作业不会导致流水线失败。
  artifacts	在成功时附加到作业的一组文件和目录。
  before_script	覆盖作业开始前执行的一组命令。
  cache	应该在后续运行之间缓存的文件列表。
  coverage	给定作业的代码覆盖率设置。
  dast_configuration	在作业级别使用来自 DAST 配置文件的配置。
  dependencies	通过提供作业列表来限制将哪些产物传递给特定作业。
  environment	作业部署到的环境名称。
  extends	此作业继承的配置条目。
  identity	使用身份联合认证与第三方服务进行身份验证。
  image	使用 Docker 镜像。
  inherit	选择所有作业继承的全局默认值。
  interruptible	定义作业是否可以在被冗余的更新运行中取消。
  manual_confirmation	为手动作业定义自定义确认消息。
  needs	比阶段顺序更早执行作业。
  pages	上传作业结果以用于极狐GitLab Pages。
  parallel	应并行运行多少个作业实例。
  release	指示 runner 生成 release 对象。
  resource_group	限制作业并发性。
  retry	在失败情况下，作业可以自动重试的时间和次数。
  rules	评估条件的列表，以确定作业的选定属性以及是否创建。
  script	由 runner 执行的 shell 脚本。
  run	由 runner 执行的运行配置。
  secrets	作业所需的 CI/CD 密钥。
  services	使用 Docker 服务镜像。
  stage	定义作业阶段。
  tags	用于选择 runner 的标签列表。
  timeout	定义自定义作业级别超时，优先于项目范围设置。
  trigger	定义下游流水线触发器。
  when	何时运行作业。

• CI/CD 变量

  关键词	描述
  默认 variables	为流水线中的所有作业定义默认 CI/CD 变量。
  作业 variables	为单个作业定义 CI/CD 变量。

全局关键词#

某些关键词未在作业中定义。这些关键词控制流水线行为或导入其他流水线配置。

default#

您可以为某些关键词设置全局默认值。每个默认关键词都会复制到所有未定义它的作业中。如果作业已经定义了关键词，则不会使用该默认值。

关键词类型：全局关键词。

支持的值：这些关键词可以有自定义默认值：

• after_script
• artifacts
• before_script
• cache
• hooks
• id_tokens
• image
• interruptible
• retry
• services
• tags
• timeout

default 示例：

yaml
1default:
2  image: ruby:3.0
3  retry: 2
4
5rspec:
6  script: bundle exec rspec
7
8rspec 2.7:
9  image: ruby:2.7
10  script: bundle exec rspec

在此示例中：

• image: ruby:3.0 和 retry: 2 是流水线中所有作业的默认关键词。
• rspec 作业未定义 image 或 retry，因此它使用默认值 image: ruby:3.0 和 retry: 2。
• rspec 2.7 作业未定义 retry，但它确实定义了 image。它使用默认 retry: 2，但忽略默认 image，并使用作业中定义的 image: ruby:2.7。

其他详细信息：

• 使用 inherit:default 控制作业中的默认关键词继承。
• 全局默认值不会传递给 下游流水线，下游流水线独立于触发它们的上游流水线运行。

include#

使用 include 在 CI/CD 配置中包含外部 YAML 文件。您可以将一个长的 .gitlab-ci.yml 文件拆分为多个文件以增加可读性，或减少多个位置相同配置的重复。

您还可以将模板文件存储在中央存储库中，并将它们包含在项目中。

include 文件为：

• 与 .gitlab-ci.yml 文件中的文件合并。
• 总是首先评估，然后与 .gitlab-ci.yml 文件的内容合并，无论 include 关键词的位置如何。

解析所有文件的时间限制为 30 秒。

关键词类型：全局关键词。

支持的值：include 子键：

• include:component
• include:local
• include:project
• include:remote
• include:template

以及可选的：

• include:inputs
• include:rules
• include:integrity

其他详细信息：

• 只有 某些 CI/CD 变量 可以与 include 关键词一起使用。
• 使用合并自定义和覆盖包含的 CI/CD 配置与本地
• 您可以通过在 .gitlab-ci.yml 文件中拥有相同的作业名称或全局关键词来覆盖包含的配置。两个配置合并在一起，.gitlab-ci.yml 文件中的配置优先于包含的配置。
• 如果您重新运行：
  • 作业，则不会再次获取 include 文件。流水线中的所有作业都使用流水线创建时获取的配置。源 include 文件的任何更改都不会影响作业重新运行。
  • 流水线，则会再次获取 include 文件。如果它们在上次流水线运行后发生了变化，新流水线将使用更改后的配置。
• 默认情况下，您可以每个流水线最多有 150 个包含，包括 嵌套。此外：
  • 在极狐GitLab 16.0 及更高版本中，极狐GitLab 私有化部署用户可以更改 最大包含 值。
  • 在极狐GitLab 15.10 及更高版本中，您可以拥有最多 150 个包含。在嵌套包含中，文件可以多次包含，但重复包含计入限制。
  • 从极狐GitLab 14.9 到 极狐GitLab 15.9，您最多可以拥有 100 个包含。在嵌套包含中，同一文件可以多次包含，但重复项将被忽略。

include:component#

使用 include:component 将 CI/CD 组件 添加到流水线配置中。

关键词类型：全局关键词。

支持的值：CI/CD 组件的完整地址，格式为 <fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>。

include:component 示例：

yaml
include:
  - component: $CI_SERVER_FQDN/my-org/security-components/secret-detection@1.0

相关主题：

• 使用 CI/CD 组件。

include:local#

使用 include:local 包含与包含 include 关键词的配置文件在同一存储库和分支中的文件。使用 include:local 而不是符号链接。

关键词类型：全局关键词。

支持的值：

一个相对于根目录的完整路径（/）：

• YAML 文件必须具有 .yml 或 .yaml 扩展名。
• 您可以在文件路径中 使用 * 和 ** 通配符。
• 您可以使用 某些 CI/CD 变量。

include:local 示例：

yaml
include:
  - local: '/templates/.gitlab-ci-template.yml'

您还可以使用较短的语法定义路径：

yaml
include: '.gitlab-ci-production.yml'

其他详细信息：

• .gitlab-ci.yml 文件和本地文件必须在同一个分支上。
• 您不能通过 Git 子模块路径包含本地文件。
• include 配置总是根据包含 include 关键词的文件的位置进行评估，而不是运行流水线的项目。如果在不同项目的配置文件中有 嵌套 include，include: local 会检查其他项目中的文件。

include:project#

要从同一极狐GitLab 实例上的另一个私有项目中包含文件，请使用 include:project 和 include:file。

关键词类型：全局关键词。

支持的值：

• include:project：完整的极狐GitLab 项目路径。
• include:file：相对于根目录（/）的完整文件路径或文件路径数组。YAML 文件必须具有 .yml 或 .yaml 扩展名。
• include:ref：可选。从中检索文件的参考。如果未指定，则默认为项目的 HEAD。
• 您可以使用 某些 CI/CD 变量。

include:project 示例：

yaml
1include:
2  - project: 'my-group/my-project'
3    file: '/templates/.gitlab-ci-template.yml'
4  - project: 'my-group/my-subgroup/my-project-2'
5    file:
6      - '/templates/.builds.yml'
7      - '/templates/.tests.yml'

您还可以指定 ref：

yaml
1include:
2  - project: 'my-group/my-project'
3    ref: main                                      # Git 分支
4    file: '/templates/.gitlab-ci-template.yml'
5  - project: 'my-group/my-project'
6    ref: v1.0.0                                    # Git 标签
7    file: '/templates/.gitlab-ci-template.yml'
8  - project: 'my-group/my-project'
9    ref: 787123b47f14b552955ca2786bc9542ae66fee5b  # Git SHA
10    file: '/templates/.gitlab-ci-template.yml'

其他详细信息：

• include 配置总是根据包含 include 关键词的文件的位置进行评估，而不是运行流水线的项目。如果在不同项目的配置文件中有 嵌套 include，include: local 会检查其他项目中的文件。
• 当流水线开始时，通过所有方法包含的 .gitlab-ci.yml 文件配置会被评估。配置是一个时间快照，并保留在数据库中。极狐GitLab 不会反映引用 .gitlab-ci.yml 文件配置的任何更改，直到下一次流水线开始。
• 当您从另一个私有项目中包含 YAML 文件时，运行流水线的用户必须是两个项目的成员，并具有运行流水线的适当权限。如果用户无权访问任何包含的文件，可能会显示 not found or access denied 错误。
• 在包含另一个项目的 CI/CD 配置文件时要小心。当 CI/CD 配置文件发生变化时，不会触发任何流水线或通知。从安全角度来看，这类似于拉取第三方依赖项。对于 ref，考虑：
  • 使用特定的 SHA 哈希，这应该是最稳定的选项。使用完整的 40 字符 SHA 哈希以确保引用所需的提交，因为在 ref 中使用短 SHA 哈希可能会不明确。
  • 在另一个项目中应用 受保护分支 和 受保护标签 规则。受保护的标签和分支更有可能在更改之前通过变更管理。

include:remote#

使用 include:remote 和完整 URL 从其他位置包含文件。

关键词类型：全局关键词。

支持的值：

可通过 HTTP/HTTPS GET 请求访问的公共 URL：

• 不支持远程 URL 的身份验证。
• YAML 文件必须具有 .yml 或 .yaml 扩展名。
• 您可以使用 某些 CI/CD 变量。

include:remote 示例：

yaml
include:
  - remote: 'https://jihulab.com/example-project/-/raw/main/.gitlab-ci.yml'

其他详细信息：

• 所有 嵌套包含 都以公共用户身份执行，没有上下文，因此您只能包含公共项目或模板。在嵌套包含的 include 部分中没有可用的变量。
• 在包含另一个项目的 CI/CD 配置文件时要小心。当其他项目的文件发生变化时，不会触发任何流水线或通知。从安全角度来看，这类似于拉取第三方依赖项。为了验证包含文件的完整性，请考虑使用 integrity 关键词。如果链接到您拥有的另一个极狐GitLab 项目，请考虑同时使用 受保护分支 和 受保护标签 来实施变更管理规则。

include:template#

使用 include:template 包含 .gitlab-ci.yml 模板。

关键词类型：全局关键词。

支持的值：

CI/CD 模板：

• 所有模板都可以在 lib/gitlab/ci/templates 中查看。并非所有模板都设计为与 include:template 一起使用，因此在使用之前检查模板注释。
• 您可以使用 某些 CI/CD 变量。

include:template 示例：

yaml
# 文件来源于极狐GitLab 模板集合
include:
  - template: Auto-DevOps.gitlab-ci.yml

多个 include:template 文件：

yaml
include:
  - template: Android-Fastlane.gitlab-ci.yml
  - template: Auto-DevOps.gitlab-ci.yml

其他详细信息：

• 所有 嵌套包含 都以公共用户身份执行，没有上下文，因此您只能包含公共项目或模板。在嵌套包含的 include 部分中没有可用的变量。

include:inputs#

使用 include:inputs 在包含的配置使用 spec:inputs 并添加到流水线时设置输入参数的值。

关键词类型：全局关键词。

支持的值：字符串、数值或布尔值。

include:inputs 示例：

yaml
include:
  - local: 'custom_configuration.yml'
    inputs:
      website: "My website"

在此示例中：

• custom_configuration.yml 中的配置被添加到流水线中，并为包含的配置设置 website 输入为 My website 的值。

其他详细信息：

• 如果包含的配置文件使用 spec:inputs:type，则输入值必须与定义的类型匹配。
• 如果包含的配置文件使用 spec:inputs:options，则输入值必须与列出的选项之一匹配。

相关主题：

• 使用 include 时设置输入值。

include:rules#

您可以使用 rules 和 include 来有条件地包含其他配置文件。

关键词类型：全局关键词。

支持的值：这些 rules 子键：

• rules:if。
• rules:exists。
• rules:changes。

一些 CI/CD 变量是支持的。

include:rules 示例：

yaml
1include:
2  - local: build_jobs.yml
3    rules:
4      - if: $INCLUDE_BUILDS == "true"
5
6test-job:
7  stage: test
8  script: echo "This is a test job"

在此示例中，如果 INCLUDE_BUILDS 变量为：

• true，则 build_jobs.yml 配置被包含在流水线中。
• 不为 true 或不存在，则 build_jobs.yml 配置不被包含在流水线中。

相关主题：

• 使用 include 的示例：
  • rules:if。
  • rules:changes。
  • rules:exists。

include:integrity#

使用 integrity 和 include:remote 来指定包含的远程文件的 SHA256 哈希。如果 integrity 与实际内容不匹配，则不处理远程文件并且流水线失败。

关键词类型：全局关键词。

支持的值：包含内容的 Base64 编码 SHA256 哈希。

include:integrity 示例：

yaml
include:
  - remote: 'https://jihulab.com/example-project/-/raw/main/.gitlab-ci.yml'
    integrity: 'sha256-L3/GAoKaw0Arw6hDCKeKQlV1QPEgHYxGBHsH4zG1IY8='

stages#

使用 stages 定义包含作业组的阶段。使用 stage 在作业中配置作业在特定阶段运行。

如果在 .gitlab-ci.yml 文件中未定义 stages，则默认的流水线阶段为：

• .pre
• build
• test
• deploy
• .post

stages 中项目的顺序定义作业的执行顺序：

• 同一阶段的作业并行运行。
• 下一阶段的作业在前一个阶段的作业成功完成后运行。

如果流水线仅包含 .pre 或 .post 阶段的作业，则不会运行。 必须至少有一个其他作业在不同阶段。

关键词类型：全局关键词。

stages 示例：

yaml
stages:
  - build
  - test
  - deploy

在此示例中：

1. build 中的所有作业并行执行。
2. 如果 build 中的所有作业成功，则 test 作业并行执行。
3. 如果 test 中的所有作业成功，则 deploy 作业并行执行。
4. 如果 deploy 中的所有作业成功，则流水线标记为 passed。

如果任何作业失败，则流水线标记为 failed，后续阶段的作业不会启动。同阶段的作业不会停止并继续运行。

其他详细信息：

• 如果作业未指定 stage，则作业被分配到 test 阶段。
• 如果定义了阶段但没有作业使用它，则该阶段在流水线中不可见，这可以帮助 合规流水线配置：
  • 阶段可以在合规配置中定义，但如果未使用则保持隐藏。
  • 当开发人员在作业定义中使用它们时，定义的阶段变得可见。

相关主题：

• 要使作业提前启动并忽略阶段顺序，请使用 needs 关键词。

workflow#

使用 workflow 控制流水线行为。

您可以在 workflow 配置中使用一些 预定义的 CI/CD 变量，但不能使用仅在作业启动时定义的变量。

相关主题：

• workflow: rules 示例
• 在分支流水线和合并请求流水线之间切换

workflow:auto_cancel:on_new_commit#

使用 workflow:auto_cancel:on_new_commit 配置 自动取消冗余流水线 功能的行为。

支持的值：

• conservative：取消流水线，但仅在尚未启动任何 interruptible: false 的作业时。未定义时默认。
• interruptible：仅取消 interruptible: true 的作业。
• none：不自动取消任何作业。

workflow:auto_cancel:on_new_commit 示例：

yaml
1workflow:
2  auto_cancel:
3    on_new_commit: interruptible
4
5job1:
6  interruptible: true
7  script: sleep 60
8
9job2:
10  interruptible: false  # 未定义时的默认值。
11  script: sleep 60

在此示例中：

• 当新提交被推送到分支时，极狐GitLab 创建一个新流水线，job1 和 job2 启动。
• 如果在作业完成之前将新提交推送到分支，则仅 job1 被取消。

workflow:auto_cancel:on_job_failure#

使用 workflow:auto_cancel:on_job_failure 配置作业失败时应自动取消哪些作业。

支持的值：

• all：作业一失败就取消流水线和所有正在运行的作业。
• none：不自动取消任何作业。

workflow:auto_cancel:on_job_failure 示例：

yaml
1stages: [stage_a, stage_b]
2
3workflow:
4  auto_cancel:
5    on_job_failure: all
6
7job1:
8  stage: stage_a
9  script: sleep 60
10
11job2:
12  stage: stage_a
13  script:
14    - sleep 30
15    - exit 1
16
17job3:
18  stage: stage_b
19  script:
20    - sleep 30

在此示例中，如果 job2 失败，则如果 job1 仍在运行则被取消，job3 不会启动。

相关主题：

• 从下游流水线自动取消父流水线

workflow:name#

您可以在 workflow: 中使用 name 为流水线定义名称。

所有流水线都被分配定义的名称。名称中的任何前导或尾随空格都被删除。

支持的值：

• 字符串。
• CI/CD 变量。
• 两者的组合。

workflow:name 示例：

使用预定义变量的简单流水线名称：

yaml
workflow:
  name: 'Pipeline for branch: $CI_COMMIT_BRANCH'

根据流水线条件配置不同流水线名称：

yaml
1variables:
2  PROJECT1_PIPELINE_NAME: 'Default pipeline name'  # 不需要默认值
3
4workflow:
5  name: '$PROJECT1_PIPELINE_NAME'
6  rules:
7    - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/'
8      variables:
9        PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline'
10    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
11      variables:
12        PROJECT1_PIPELINE_NAME: 'MR pipeline: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
13    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # 对于默认分支流水线，使用默认名称

其他详细信息：

• 如果名称为空字符串，则不会为流水线分配名称。如果名称仅由 CI/CD 变量组成，且所有变量也为空，则会评估为空字符串。
• workflow:rules:variables 成为所有作业的 默认变量，包括 trigger 作业，默认情况下将变量转发到下游流水线。如果下游流水线使用相同的变量，则 变量被上游变量值覆盖。请确保：
  • 在每个项目的流水线配置中使用唯一的变量名称，例如 PROJECT1_PIPELINE_NAME。
  • 在触发作业中使用 inherit:variables，并列出您希望转发到下游流水线的确切变量。

workflow:rules#

workflow 中的 rules 关键词类似于作业级别的 rules，但控制是否创建整个流水线。

当没有规则评估为 true 时，流水线不会运行。

支持的值：您可以使用与作业级别 rules 相同的关键词：

• rules: if。
• rules: changes。
• rules: exists。
• when，在 workflow 中使用时只能是 always 或 never。
• variables。

workflow:rules 示例：

yaml
1workflow:
2  rules:
3    - if: $CI_COMMIT_TITLE =~ /-draft$/
4      when: never
5    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
6    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

在此示例中，流水线运行条件为提交标题（提交消息的第一行）不以 -draft 结尾，并且流水线是：

• 合并请求
• 默认分支。

其他详细信息：

• 如果您的规则同时匹配分支流水线（除默认分支外）和合并请求流水线，则可能会发生 重复流水线。
• start_in、allow_failure 和 needs 在 workflow:rules 中不受支持，但不会导致语法错误。虽然它们没有效果，但不要在 workflow:rules 中使用它们，因为将来可能会导致语法错误。

相关主题：

• 常见的 if 子句用于 workflow:rules。
• 使用 rules 运行合并请求流水线。

workflow:rules:variables#

您可以在 workflow:rules 中使用 variables 为特定流水线条件定义变量。

当条件匹配时，变量被创建并可供流水线中的所有作业使用。如果变量已经作为默认变量在顶层定义，则 workflow 变量具有优先级并覆盖默认变量。

关键词类型：全局关键词。

支持的值：变量名称和值对：

• 名称只能使用数字、字母和下划线 (_)。
• 值必须是字符串。

workflow:rules:variables 示例：

yaml
1variables:
2  DEPLOY_VARIABLE: "default-deploy"
3
4workflow:
5  rules:
6    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
7      variables:
8        DEPLOY_VARIABLE: "deploy-production"  # 覆盖全局定义的 DEPLOY_VARIABLE
9    - if: $CI_COMMIT_BRANCH =~ /feature/
10      variables:
11        IS_A_FEATURE: "true"                  # 定义一个新变量。
12    - if: $CI_COMMIT_BRANCH                   # 在其他情况下运行流水线
13
14job1:
15  variables:
16    DEPLOY_VARIABLE: "job1-default-deploy"
17  rules:
18    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
19      variables:                                   # 覆盖在作业级别定义的 DEPLOY_VARIABLE。
20        DEPLOY_VARIABLE: "job1-deploy-production"
21    - when: on_success                             # 在其他情况下运行作业
22  script:
23    - echo "Run script with $DEPLOY_VARIABLE as an argument"
24    - echo "Run another script if $IS_A_FEATURE exists"
25
26job2:
27  script:
28    - echo "Run script with $DEPLOY_VARIABLE as an argument"
29    - echo "Run another script if $IS_A_FEATURE exists"

当分支是默认分支时：

• job1 的 DEPLOY_VARIABLE 是 job1-deploy-production。
• job2 的 DEPLOY_VARIABLE 是 deploy-production。

当分支是 feature 时：

• job1 的 DEPLOY_VARIABLE 是 job1-default-deploy，IS_A_FEATURE 是 true。
• job2 的 DEPLOY_VARIABLE 是 default-deploy，IS_A_FEATURE 是 true。

当分支是其他分支时：

• job1 的 DEPLOY_VARIABLE 是 job1-default-deploy。
• job2 的 DEPLOY_VARIABLE 是 default-deploy。

其他详细信息：

• workflow:rules:variables 成为所有作业的 默认变量，包括 trigger 作业，默认情况下将变量转发到下游流水线。如果下游流水线使用相同的变量，则 变量被上游变量值覆盖。请确保：
  • 在每个项目的流水线配置中使用唯一的变量名称，例如 PROJECT1_VARIABLE_NAME。
  • 在触发作业中使用 inherit:variables，并列出您希望转发到下游流水线的确切变量。

workflow:rules:auto_cancel#

使用 workflow:rules:auto_cancel 配置 workflow:auto_cancel:on_new_commit 或 workflow:auto_cancel:on_job_failure 功能的行为。

支持的值：

• on_new_commit：workflow:auto_cancel:on_new_commit
• on_job_failure：workflow:auto_cancel:on_job_failure

workflow:rules:auto_cancel 示例：

yaml
1workflow:
2  auto_cancel:
3    on_new_commit: interruptible
4    on_job_failure: all
5  rules:
6    - if: $CI_COMMIT_REF_PROTECTED == 'true'
7      auto_cancel:
8        on_new_commit: none
9        on_job_failure: none
10    - when: always                  # 在其他情况下运行流水线
11
12test-job1:
13  script: sleep 10
14  interruptible: false
15
16test-job2:
17  script: sleep 10
18  interruptible: true

在此示例中，默认情况下所有作业的 workflow:auto_cancel:on_new_commit 设置为 interruptible，并且 workflow:auto_cancel:on_job_failure 设置为 all。但是，如果流水线在受保护分支上运行，则规则会覆盖默认值，设置 on_new_commit: none 和 on_job_failure: none。例如，如果流水线正在为：

• 非受保护分支运行并且新提交被推送，则 test-job1 继续运行，test-job2 被取消。
• 受保护分支运行并且新提交被推送，则 test-job1 和 test-job2 都继续运行。

头部关键词#

某些关键词必须在 YAML 配置文件的头部部分定义。头部必须位于文件顶部，并与配置的其他部分用 --- 分隔。

spec#

在 YAML 文件的头部添加 spec 部分以配置流水线的行为，配置在流水线中使用 include 关键词添加时。

规格必须在配置文件顶部声明，位于头部部分，并与配置的其他部分用 --- 分隔。

spec:inputs#

您可以使用 spec:inputs 为 CI/CD 配置定义 输入。

使用插值格式 $[[ inputs.input-id ]] 引用头部部分外的值。当配置在流水线创建期间被获取时，输入会被评估和插值。当使用输入时，插值在配置与 .gitlab-ci.yml 文件的内容合并之前完成。

关键词类型：头部关键词。spec 必须在配置文件顶部声明，位于头部部分。

支持的值：表示预期输入的字符串哈希。

spec:inputs 示例：

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

其他详细信息：

• 输入是强制性的，除非您使用 spec:inputs:default 设置默认值。避免强制输入，除非您仅使用 include:inputs 输入。
• 输入期望字符串，除非您使用 spec:inputs:type 设置不同的输入类型。
• 包含插值块的字符串不能超过 1 MB。
• 插值块中的字符串不能超过 1 KB。
• 您可以在运行新流水线时 定义输入值。

相关主题：

• 使用 spec:inputs 定义输入参数。

spec:inputs:default#

在包含输入时，输入是强制性的，除非您使用 spec:inputs:default 设置默认值。

使用 default: '' 表示没有默认值。

关键词类型：头部关键词。spec 必须在配置文件顶部的头部部分声明。

支持的值：表示默认值的字符串，或 ''。

spec:inputs:default 的示例：

yaml
1spec:
2  inputs:
3    website:
4    user:
5      default: 'test-user'
6    flags:
7      default: ''
8title: The pipeline configuration would follow...
9---

在此示例中：

1. website 是必需的，必须定义。
2. user 是可选的。如果未定义，则值为 test-user。
3. flags 是可选的。如果未定义，则没有值。

附加细节：

1. 当输入使用 default 和 options 时，如果默认值不是列出选项之一，流水线会因验证错误而失败。
2. 当输入使用 default 和 regex 时，如果默认值不匹配正则表达式，流水线会因验证错误而失败。
3. 值不匹配 type 时，流水线会因验证错误而失败。

spec:inputs:description#

使用 description 为特定输入提供描述。描述不影响输入的行为，仅用于帮助文件用户理解输入。

关键词类型：头部关键词。spec 必须在配置文件顶部的头部部分声明。

支持的值：表示描述的字符串。

spec:inputs:description 的示例：

yaml
1spec:
2  inputs:
3    flags:
4      description: 'Sample description of the `flags` input details.'
5title: The pipeline configuration would follow...
6---

spec:inputs:options#

输入可以使用 options 为输入指定一个允许值的列表。每个输入的选项上限为 50 个。

关键词类型：头部关键词。spec 必须在配置文件顶部的头部部分声明。

支持的值：一个输入选项的数组。

spec:inputs:options 的示例：

yaml
1spec:
2  inputs:
3    environment:
4      options:
5        - development
6        - staging
7        - production
8title: The pipeline configuration would follow...
9---

在此示例中：

1. environment 是必需的，必须定义为列表中的一个值。

附加细节：

1. 当输入使用 options 和 default 时，如果默认值不是列出选项之一，流水线会因验证错误而失败。
2. 当输入选项不匹配 type 时，流水线会因验证错误而失败，type 可以是 string 或 number，但在使用 options 时不能是 boolean。

spec:inputs:regex#

使用 spec:inputs:regex 来指定输入必须匹配的正则表达式。

关键词类型：头部关键词。spec 必须在配置文件顶部的头部部分声明。

支持的值：必须是正则表达式。

spec:inputs:regex 的示例：

yaml
1spec:
2  inputs:
3    version:
4      regex: ^v\d\.\d+(\.\d+)$
5title: The pipeline configuration would follow...
6---

在此示例中，v1.0 或 v1.2.3 的输入匹配正则表达式并通过验证。v1.A.B 的输入不匹配正则表达式并验证失败。

附加细节：

1. inputs:regex 只能与 string 类型的 type 一起使用，不能与 number 或 boolean 一起使用。
2. 不要使用 / 字符包围正则表达式。例如，使用 regex.*，而不是 /regex.*/。
3. inputs:regex 使用 RE2 解析正则表达式。

spec:inputs:type#

默认情况下，输入期望为字符串。使用 spec:inputs:type 来设置输入所需的不同类型。

关键词类型：头部关键词。spec 必须在配置文件顶部的头部部分声明。

支持的值：可以是以下之一：

1. array，接受输入的数组。
2. string，接受字符串输入（未定义时默认）。
3. number，仅接受数字输入。
4. boolean，仅接受 true 或 false 输入。

spec:inputs:type 的示例：

yaml
1spec:
2  inputs:
3    job_name:
4    website:
5      type: string
6    port:
7      type: number
8    available:
9      type: boolean
10    array_input:
11      type: array
12title: The pipeline configuration would follow...
13---

任务关键词#

以下主题解释如何使用关键词配置 CI/CD 流水线。

after_script#

使用 after_script 定义一组命令，这些命令将在任务的 before_script 和 script 部分完成后最后运行。即使在以下情况下，after_script 命令也会运行：

1. 当 before_script 或 script 部分仍在运行时任务被取消。
2. 任务因 script_failure 类型而失败，而不是其他失败类型。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：一个包含以下内容的数组：

1. 单行命令。
2. 分多行的长命令。
3. YAML 锚点。

CI/CD 变量被支持。

after_script 的示例：

yaml
job:
  script:
    - echo "An example script section."
  after_script:
    - echo "Execute this command after the `script` section completes."

附加细节：

在 after_script 中指定的脚本在一个新 shell 中执行，与任何 before_script 或 script 命令分开。因此，它们：

1. 当前工作目录设置为默认（根据定义 runner 处理 Git 请求的变量）。
2. 无法访问 before_script 或 script 中命令所做的更改，包括：
   • 在 script 脚本中导出的命令别名和变量。
   • 工作树之外的更改（取决于 runner 执行器），例如由 before_script 或 script 脚本安装的软件。
3. 拥有单独的超时时间。对于极狐GitLab Runner 16.4 及更高版本，默认为 5 分钟，可以通过RUNNER_AFTER_SCRIPT_TIMEOUT 变量配置。在极狐GitLab 16.3 及更早版本中，超时硬编码为 5 分钟。
4. 不影响任务的退出代码。如果 script 部分成功并且 after_script 超时或失败，则任务以代码 0（任务成功）退出。
5. 使用 CI/CD 任务令牌 与 after_script 存在已知问题。您可以在 after_script 命令中使用任务令牌进行身份验证，但如果任务被取消，令牌立即失效。

对于超时的任务：

1. 默认情况下不会执行 after_script 命令。
2. 您可以通过设置适当的 RUNNER_SCRIPT_TIMEOUT 和 RUNNER_AFTER_SCRIPT_TIMEOUT 值来配置超时值，以确保 after_script 运行，这些值不超过任务的超时时间。

相关主题：

1. 将 after_script 与 default 一起使用，为所有任务定义一组默认命令，这些命令应在所有任务后运行。
2. 您可以配置任务以在任务被取消时跳过 after_script 命令。
3. 您可以忽略非零退出代码。
4. 在 after_script 中使用颜色代码，使任务日志更易于查看。
5. 创建自定义可折叠部分，以简化任务日志输出。
6. 您可以忽略 after_script 中的错误。

allow_failure#

使用 allow_failure 确定当任务失败时流水线是否应继续运行。

1. 要让流水线继续运行后续任务，请使用 allow_failure: true。
2. 要阻止流水线运行后续任务，请使用 allow_failure: false。

当允许任务失败（allow_failure: true）时，一个橙色警告 (

) 表示任务失败。然而，流水线仍然成功，关联的提交被标记为通过且没有警告。

当以下情况出现时，也会显示相同的警告：

1. 阶段中的所有其他任务都成功。
2. 流水线中的所有其他任务都成功。

allow_failure 的默认值为：

1. 手动任务为 true。
2. 使用 when: manual 和 rules 的任务为 false。
3. 其他情况下为 false。

关键词类型：任务关键词。您只能将其作为任务的一部分使用。

支持的值：

1. true 或 false。

allow_failure 的示例：

yaml
1job1:
2  stage: test
3  script:
4    - execute_script_1
5
6job2:
7  stage: test
8  script:
9    - execute_script_2
10  allow_failure: true
11
12job3:
13  stage: deploy
14  script:
15    - deploy_to_staging
16  environment: staging

在此示例中，job1 和 job2 并行运行：

1. 如果 job1 失败，deploy 阶段中的任务不会开始。
2. 如果 job2 失败，deploy 阶段中的任务仍然可以开始。

附加细节：

1. 您可以将 allow_failure 作为 rules 的子键使用。
2. 如果设置了 allow_failure: true，任务始终被视为成功，并且使用 when: on_failure 的后续任务在此任务失败时不会启动。
3. 您可以使用 allow_failure: false 和手动任务来创建一个阻塞的手动任务。阻塞的流水线在手动任务启动并成功完成之前不会运行任何后续阶段的任务。

allow_failure:exit_codes#

使用 allow_failure:exit_codes 来控制任务何时可以失败。对于列出的任一退出代码，任务为 allow_failure: true，对于任何其他退出代码，任务为 allow_failure: false。

关键词类型：任务关键词。您只能将其作为任务的一部分使用。

支持的值：

1. 单个退出代码。
2. 一组退出代码。

allow_failure 的示例：

yaml
1test_job_1:
2  script:
3    - echo "Run a script that results in exit code 1. This job fails."
4    - exit 1
5  allow_failure:
6    exit_codes: 137
7
8test_job_2:
9  script:
10    - echo "Run a script that results in exit code 137. This job is allowed to fail."
11    - exit 137
12  allow_failure:
13    exit_codes:
14      - 137
15      - 255

artifacts#

使用 artifacts 指定要保存为任务产物的文件。任务产物是附加到任务的文件和目录列表，当任务成功、失败或始终时可用。

任务结束后，产物会被发送到极狐GitLab。如果大小小于最大产物大小，则可以在极狐GitLab UI 中下载。

默认情况下，后续阶段的任务会自动下载早期阶段任务创建的所有产物。您可以在任务中使用 dependencies 控制产物下载行为。

使用 needs 关键字时，任务只能从 needs 配置中定义的任务下载产物。

默认情况下，仅成功的任务收集任务产物，并且产物在缓存之后恢复。

了解有关产物的更多信息。

artifacts:paths#

路径是相对于项目目录 ($CI_PROJECT_DIR) 的，不能直接链接到其外部。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：

1. 文件路径数组，相对于项目目录。
2. 您可以使用 glob 模式和 doublestar.Glob 模式的通配符。
3. 对于 GitLab Pages 任务：
   • 在极狐GitLab 17.10 及更高版本中，pages.publish 路径会自动附加到 artifacts:paths，因此无需再次指定。
   • 在极狐GitLab 17.10 及更高版本中，当未指定 pages.publish 路径时，public 目录会自动附加到 artifacts:paths。

CI/CD 变量被支持。

artifacts:paths 的示例：

yaml
job:
  artifacts:
    paths:
      - binaries/
      - .config

此示例创建一个包含 .config 文件和 binaries 目录中所有文件的产物。

附加细节：

1. 如果不与 artifacts:name 一起使用，产物文件将命名为 artifacts，下载时变为 artifacts.zip。

相关主题：

1. 要限制特定任务获取产物的任务，请参见 dependencies。
2. 创建任务产物。

artifacts:exclude#

使用 artifacts:exclude 防止文件被添加到产物归档中。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：

1. 文件路径数组，相对于项目目录。
2. 您可以使用 glob 或 doublestar.PathMatch 模式的通配符。

artifacts:exclude 的示例：

yaml
artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/**/*.o

此示例存储 binaries/ 中的所有文件，但不包括位于 binaries/ 子目录中的 *.o 文件。

附加细节：

1. artifacts:exclude 路径不会被递归搜索。
2. 通过 artifacts:untracked 匹配的文件也可以使用 artifacts:exclude 排除。

相关主题：

1. 从任务产物中排除文件。

artifacts:expire_in#

使用 expire_in 指定任务产物在到期并被删除之前存储的时间。expire_in 设置不影响：

1. 最新任务的产物，除非在项目级别或实例范围内禁用保留最新任务产物。

到期后，产物默认每小时删除一次（使用 cron 作业），不再可访问。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：过期时间。如果未提供单位，则时间以秒为单位。有效值包括：

• '42'
• 42 seconds
• 3 mins 4 sec
• 2 hrs 20 min
• 2h20min
• 6 mos 1 day
• 47 yrs 6 mos and 4d
• 3 weeks and 2 days
• never

artifacts:expire_in 的示例：

yaml
job:
  artifacts:
    expire_in: 1 week

附加细节：

1. 过期时间段从产物上传并存储到极狐GitLab 时开始计算。如果未定义过期时间，则默认为实例范围设置。
2. 要覆盖过期日期并保护产物不被自动删除：
   • 在任务页面选择 Keep。
   • 将 expire_in 的值设置为 never。
3. 如果过期时间太短，长流水线的后续阶段任务可能会尝试从早期任务获取已过期的产物。如果产物已过期，尝试获取它们的任务将失败并出现could not retrieve the needed artifacts 错误。将过期时间设置得更长，或在后续任务中使用 dependencies 确保它们不会尝试获取过期的产物。
4. artifacts:expire_in 不影响极狐GitLab Pages 部署。要配置 Pages 部署的过期，请使用 pages.expire_in。

artifacts:expose_as#

使用 artifacts:expose_as 关键字在合并请求 UI 中公开任务产物。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：

1. 在合并请求 UI 中显示产物下载链接的名称。必须与 artifacts:paths 结合使用。

artifacts:expose_as 的示例：

yaml
test:
  script: ["echo 'test' > file.txt"]
  artifacts:
    expose_as: 'artifact 1'
    paths: ['file.txt']

附加细节：

1. 如果 artifacts:paths 的值：
   • 使用 CI/CD 变量，产物会被保存，但不会在 UI 中显示。
   • 定义了一个目录，但未以 / 结尾。例如，directory/ 可与 artifacts:expose_as 一起使用，但 directory 不可。
   • 以 ./ 开头。例如，file 可与 artifacts:expose_as 一起使用，但 ./file 不可。
2. 每个合并请求最多可以公开 10 个任务产物。
3. 不支持全局模式。
4. 如果指定了一个目录并且目录中有多个文件，则链接到任务产物浏览器。
5. 如果启用了极狐GitLab Pages，极狐GitLab 会自动呈现产物，当产物是单个文件并具有以下扩展名之一时：
   • .html 或 .htm
   • .txt
   • .json
   • .xml
   • .log

相关主题：

1. 在合并请求 UI 中公开任务产物。

artifacts:name#

使用 artifacts:name 关键字定义创建的产物归档的名称。您可以为每个归档指定一个唯一名称。

如果未定义，默认名称为 artifacts，下载时变为 artifacts.zip。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：

1. 产物归档的名称。CI/CD 变量被支持。必须与 artifacts:paths 结合使用。

artifacts:name 的示例：

要创建一个名称为当前任务的归档：

yaml
job:
  artifacts:
    name: "job1-artifacts-file"
    paths:
      - binaries/

相关主题：

1. 使用 CI/CD 变量定义产物配置

artifacts:public#

使用 artifacts:public 确定任务产物是否应该公开可用。

当 artifacts:public 为 true（默认）时，公共流水线中的产物可供匿名用户、访客和报告者用户下载。

要拒绝匿名用户、访客和报告者用户对公共流水线中产物的读取访问权限，请将 artifacts:public 设置为 false：

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：

1. true（如果未定义则为默认值）或 false。

artifacts:public 的示例：

yaml
job:
  artifacts:
    public: false

artifacts:access#

使用 artifacts:access 来确定谁可以从极狐GitLab UI 或 API 访问任务产物。此选项不阻止您将产物转发到下游流水线。

您不能在同一任务中使用 artifacts:public 和 artifacts:access。

关键词类型：任务关键词。您只能将其作为任务的一部分使用。

支持的值：

1. all（默认）：公共流水线中的任务产物可供任何人下载，包括匿名用户、访客和报告者用户。
2. developer：只有具有开发者角色或更高角色的用户才能下载任务中的产物。
3. none：任务中的产物不允许任何人下载。

artifacts:access 的示例：

yaml
job:
  artifacts:
    access: 'developer'

附加细节：

1. artifacts:access 也影响所有 artifacts:reports，因此您还可以限制报告产物的访问。

artifacts:reports#

使用 artifacts:reports 收集由任务中包含的模板生成的产物。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：

1. 查看可用产物报告类型的列表。

artifacts:reports 的示例：

yaml
1rspec:
2  stage: test
3  script:
4    - bundle install
5    - rspec --format RspecJunitFormatter --out rspec.xml
6  artifacts:
7    reports:
8      junit: rspec.xml

附加细节：

1. 使用子流水线的产物合并父流水线中的报告不支持。
2. 要能够浏览和下载报告输出文件，请包含 artifacts:paths 关键字。这会将产物上传和存储两次。
3. 为 artifacts: reports 创建的产物始终会被上传，无论任务结果如何（成功或失败）。您可以使用 artifacts:expire_in 为产物设置过期日期。

artifacts:untracked#

使用 artifacts:untracked 将所有 Git 未跟踪的文件添加为产物（以及 artifacts:paths 中定义的路径）。artifacts:untracked 忽略存储库的 .gitignore 配置，因此 .gitignore 中匹配的产物也会被包括在内。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：

1. true 或 false（如果未定义则为默认值）。

artifacts:untracked 的示例：

保存所有 Git 未跟踪的文件：

yaml
job:
  artifacts:
    untracked: true

相关主题：

1. 将未跟踪的文件添加到产物中。

artifacts:when#

使用 artifacts:when 在任务失败时或尽管失败时上传产物。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：

1. on_success（默认）：仅在任务成功时上传产物。
2. on_failure：仅在任务失败时上传产物。
3. always：始终上传产物（除非任务超时）。例如，当需要上传产物以便解决失败的测试时。

artifacts:when 的示例：

yaml
job:
  artifacts:
    when: on_failure

附加细节：

1. 为 artifacts:reports 创建的产物始终会被上传，无论任务结果如何（成功或失败）。artifacts:when 不会改变此行为。

before_script#

使用 before_script 定义一组命令，这些命令应在每个任务的 script 命令之前运行，但在产物恢复之后。

关键词类型：任务关键词。您只能将其作为任务的一部分或在default 部分中使用。

支持的值：一个包含以下内容的数组：

1. 单行命令。
2. 分多行的长命令。
3. YAML 锚点。

CI/CD 变量被支持。

before_script 的示例：

yaml
job:
  before_script:
    - echo "Execute this command before any 'script:' commands."
  script:
    - echo "This command executes after the job's 'before_script' commands."

附加细节：

1. 您在 before_script 中指定的脚本与您在主要 script 中指定的任何脚本连接在一起。组合后的脚本在一个 shell 中一起执行。
2. 在顶层使用 before_script，但不在 default 部分中，已弃用。

相关主题：

1. 将 before_script 与 default 一起使用，为所有任务定义一组默认命令，这些命令应在所有任务的 script 命令之前运行。
2. 您可以忽略非零退出代码。
3. 在 before_script 中使用颜色代码，使任务日志更易于查看。
4. 创建自定义可折叠部分，以简化任务日志输出。

cache#

使用 cache 指定要在任务之间缓存的文件和目录列表。您只能使用本地工作副本中的路径。

缓存：

1. 在流水线和任务之间共享。
2. 默认情况下，不在受保护和未受保护的分支之间共享。
3. 在产物之前恢复。
4. 限制为最多四个不同的缓存。

您可以禁用特定任务的缓存，例如覆盖：

1. 使用 default 定义的默认缓存。
2. 使用 include 添加的任务配置。

有关缓存的更多信息，请参见极狐GitLab CI/CD 中的缓存。

#### environment:url#

为环境设置一个 URL。

关键字类型: 作业关键字。你只能在作业中使用它。

支持的值: 单个 URL，格式如下：

• 纯文本，例如 https://prod.example.com。
• CI/CD 变量，包括预定义的、项目、群组、实例，或在 .gitlab-ci.yml 文件中定义的变量。你不能使用在 script 部分定义的变量。

environment:url 示例：

yaml
1deploy to production:
2  stage: deploy
3  script: git push production HEAD:main
4  environment:
5    name: production
6    url: https://prod.example.com

附加细节：

• 作业完成后，你可以通过在合并请求、环境或部署页面选择一个按钮来访问 URL。

#### environment:on_stop#

可以通过在 environment 下定义的 on_stop 关键字关闭（停止）环境。它声明了一个不同的作业来关闭环境。

关键字类型: 作业关键字。你只能在作业中使用它。

附加细节：

• 查看 environment:action 以获取更多详细信息和示例。

#### environment:action#

使用 action 关键字来指定作业与环境的交互方式。

关键字类型: 作业关键字。你只能在作业中使用它。

支持的值: 下列关键字之一：

environment:action 示例：

yaml
1stop_review_app:
2  stage: deploy
3  variables:
4    GIT_STRATEGY: none
5  script: make delete-app
6  when: manual
7  environment:
8    name: review/$CI_COMMIT_REF_SLUG
9    action: stop

#### environment:auto_stop_in#

auto_stop_in 关键字指定了环境的生命周期。当环境过期时，极狐GitLab 会自动停止它。

关键字类型: 作业关键字。你只能在作业中使用它。

支持的值: 用自然语言写的时间段。例如，这些都是等效的：

• 168 hours
• 7 days
• one week
• never

CI/CD 变量 得到支持。

environment:auto_stop_in 示例：

yaml
review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    auto_stop_in: 1 day

当为 review_app 创建环境时，环境的生命周期设置为 1 day。每次部署审查应用时，该生命周期也重置为 1 day。

auto_stop_in 关键字可以用于所有环境操作，除了 stop。某些操作可以用于重置环境的计划停止时间。有关更多信息，请参阅出于准备或验证目的访问环境。

相关主题：

• 环境自动停止文档。

#### environment:kubernetes#

使用 kubernetes 关键字为环境配置 Kubernetes 仪表板。

关键字类型: 作业关键字。你只能在作业中使用它。

支持的值：

• agent: 指定极狐GitLab Kubernetes 代理的字符串。格式为 path/to/agent/project:agent-name。
• namespace: 表示 Kubernetes 命名空间的字符串。需要与 agent 关键字一起设置。
• flux_resource_path: 表示 Flux 资源路径的字符串。必须是完整的资源路径。需要与 agent 和 namespace 关键字一起设置。

environment:kubernetes 示例：

yaml
1deploy:
2  stage: deploy
3  script: make deploy-app
4  environment:
5    name: production
6    kubernetes:
7      agent: path/to/agent/project:agent-name
8      namespace: my-namespace
9      flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/gitlab-agent/helmreleases/gitlab-agent

此配置将 deploy 作业设置为部署到 production 环境，将名为 agent-name 的代理与环境关联，并为环境配置 Kubernetes 仪表板，命名空间为 my-namespace，flux_resource_path 设置为 helm.toolkit.fluxcd.io/v2/namespaces/gitlab-agent/helmreleases/gitlab-agent。

附加细节：

• 要使用仪表板，你必须安装极狐GitLab Kubernetes 代理并为环境的项目或其父群组配置 user_access。
• 运行作业的用户必须被授权访问集群代理。否则，将忽略 agent、namespace 和 flux_resource_path 属性。

#### environment:deployment_tier#

使用 deployment_tier 关键字指定部署环境的层级。

关键字类型: 作业关键字。你只能在作业中使用它。

支持的值: 以下之一：

• production
• staging
• testing
• development
• other

environment:deployment_tier 示例：

yaml
deploy:
  script: echo
  environment:
    name: customer-portal
    deployment_tier: production

附加细节：

• 从此作业定义创建的环境根据此值被分配一个层级。
• 如果稍后添加此值，现有环境不会更新其层级。必须通过环境 API更新现有环境的层级。

相关主题：

• 环境的部署层级。

#### 动态环境#

使用 CI/CD 变量动态命名环境。

例如：

yaml
1deploy as review app:
2  stage: deploy
3  script: make deploy
4  environment:
5    name: review/$CI_COMMIT_REF_SLUG
6    url: https://$CI_ENVIRONMENT_SLUG.example.com/

deploy as review app 作业被标记为部署，以动态创建 review/$CI_COMMIT_REF_SLUG 环境。$CI_COMMIT_REF_SLUG 是由 runner 设置的 CI/CD 变量。$CI_ENVIRONMENT_SLUG 变量基于环境名称，但适合包含在 URL 中。如果 deploy as review app 作业在名为 pow 的分支中运行，则可以通过类似 https://review-pow.example.com/ 的 URL 访问此环境。

### extends#

使用 extends 重用配置部分。它是 YAML 锚 的替代方案，更灵活且可读性更高。

关键字类型: 作业关键字。你只能在作业中使用它。

支持的值：

• 流水线中另一个作业的名称。
• 流水线中其他作业名称的列表（数组）。

extends 示例：

yaml
1.tests:
2  stage: test
3  image: ruby:3.0
4
5rspec:
6  extends: .tests
7  script: rake rspec
8
9rubocop:
10  extends: .tests
11  script: bundle exec rubocop

在此示例中，rspec 作业使用 .tests 模板作业的配置。创建流水线时，极狐GitLab：

• 基于键执行反向深度合并。
• 将 .tests 内容与 rspec 作业合并。
• 不合并键的值。

合并后的配置等同于这些作业：

yaml
1rspec:
2  stage: test
3  image: ruby:3.0
4  script: rake rspec
5
6rubocop:
7  stage: test
8  image: ruby:3.0
9  script: bundle exec rubocop

附加细节：

• 你可以为 extends 使用多个父级。
• extends 关键字支持最多十一级继承，但应避免使用超过三级。
• 在上面的示例中，.tests 是一个隐藏作业，但你也可以从常规作业中扩展配置。

相关主题：

• 通过使用 extends 重用配置部分。
• 使用 extends 从包含的配置文件中重用配置。

### hooks#

使用 hooks 指定在作业执行的某些阶段在 runner 上执行的命令列表，例如在检索 Git 仓库之前。

关键字类型: 作业关键字。你只能在作业或默认部分中使用它。

支持的值：

• 钩子及其命令的哈希。可用的钩子：pre_get_sources_script。

#### hooks:pre_get_sources_script#

使用 hooks:pre_get_sources_script 指定在克隆 Git 仓库和任何子模块之前在 runner 上执行的命令列表。你可以用于：

• 调整 Git 配置。
• 导出跟踪变量。

支持的值: 包括以下内容的数组：

• 单行命令。
• 拆分成多行的长命令。
• YAML 锚。

CI/CD 变量 得到支持。

hooks:pre_get_sources_script 示例：

yaml
job1:
  hooks:
    pre_get_sources_script:
      - echo 'hello job1 pre_get_sources_script'
  script: echo 'hello job1 script'

相关主题：

• 极狐GitLab Runner 配置

pages

使用 pages 来定义一个 极狐GitLab Pages 任务，该任务将静态内容上传到极狐GitLab。然后，这些内容会被发布为一个网站。

你必须：

1. 定义 pages: true 来发布一个名为 public 的目录。
2. 或者，如果想使用不同的内容目录，可以定义 pages.publish。

关键词类型：任务关键词或任务名称（已弃用）。你只能将其用作任务的一部分。

支持的值：

• 布尔值。当设置为 true 时，使用默认配置。
• 配置选项的哈希，详见以下章节。

pages 示例：

yaml
1create-pages:
2  stage: deploy
3  script:
4    - mv my-html-content public
5  pages: true  # 指定这是一个 Pages 任务并发布默认的 public 目录
6  rules:
7    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
8  environment: production

此示例将 my-html-content/ 目录重命名为 public/。此目录作为产物导出并通过极狐GitLab Pages 发布。

使用配置哈希的示例：

yaml
1create-pages:
2  stage: deploy
3  script:
4    - echo "nothing to do here"
5  pages:  # 指定这是一个 Pages 任务并发布默认的 public 目录
6    publish: my-html-content
7    expire_in: "1 week"
8  rules:
9    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
10  environment: production

此示例不移动目录，而是直接使用 publish 属性。它还配置了页面部署在一周后被取消发布。

弃用：使用 pages 作为任务名称

使用 pages 作为任务名称的结果与指定 Pages 属性 pages: true 的行为相同。此方法用于向后兼容，但可能不会接收 Pages 任务配置的所有未来改进。

使用 pages 作为任务名称的示例：

yaml
1pages:  # 指定这是一个 Pages 任务并发布默认的 public 目录
2  stage: deploy
3  script:
4    - mv my-html-content public
5  rules:
6    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
7  environment: production

要使用 pages 作为任务名称而不触发 Pages 部署，请将 pages 属性设置为 false：

yaml
1pages:
2  stage: deploy
3  script:
4    - mv my-html-content public
5  pages: false # 此任务不会触发 Pages 部署
6  rules:
7    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
8  environment: production

pages.publish

使用 pages.publish 来配置 pages 任务 的内容目录。从极狐GitLab 17.9 开始，顶层的 publish 关键词已弃用，现在必须嵌套在 pages 关键词下。

关键词类型：任务关键词。你只能将其用作 pages 任务的一部分。

支持的值：包含 Pages 内容的目录路径。在极狐GitLab 17.10 及更高版本中，如果未指定，则使用默认的 public 目录；如果指定，则此路径会自动附加到 artifacts:paths 中。

pages.publish 示例：

yaml
1create-pages:
2  stage: deploy
3  script:
4    - npx @11ty/eleventy --input=path/to/eleventy/root --output=dist
5  pages:
6    publish: dist  # 此路径自动附加到 artifacts:paths
7  rules:
8    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
9  environment: production

此示例使用 Eleventy 生成一个静态网站，并将生成的 HTML 文件输出到 dist/ 目录。此目录作为产物导出并通过极狐GitLab Pages 发布。

在 pages.publish 字段中也可以使用变量。例如：

yaml
1create-pages:
2  stage: deploy
3  script:
4    - mkdir -p $CUSTOM_FOLDER/$CUSTOM_PATH
5    - cp -r public $CUSTOM_FOLDER/$CUSTOM_SUBFOLDER
6  pages:
7    publish: $CUSTOM_FOLDER/$CUSTOM_SUBFOLDER  # 此路径自动附加到 artifacts:paths
8  rules:
9    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
10  variables:
11    CUSTOM_FOLDER: "custom_folder"
12    CUSTOM_SUBFOLDER: "custom_subfolder"

指定的发布路径必须相对于构建根目录。

pages.path_prefix

使用 pages.path_prefix 为极狐GitLab Pages 的并行部署配置路径前缀。

关键词类型：任务关键词。你只能将其用作 pages 任务的一部分。

支持的值：

• 一个字符串。
• CI/CD 变量。
• 两者的组合。

给定的值被转换为小写并缩短为 63 个字节。除字母数字字符或句号外的所有内容都被替换为连字符。不允许前导和尾随的连字符或句号。

pages.path_prefix 示例：

yaml
1create-pages:
2  stage: deploy
3  script:
4    - echo "Pages accessible through ${CI_PAGES_URL}/${CI_COMMIT_BRANCH}"
5  pages:  # 指定这是一个 Pages 任务并发布默认的 public 目录
6    path_prefix: "$CI_COMMIT_BRANCH"

在此示例中，为每个分支创建了不同的页面部署。

pages.expire_in

使用 expire_in 来指定一个部署在过期前应可用多长时间。部署过期后，它会被每 10 分钟运行一次的 cron 任务停用。

默认情况下，并行部署会在 24 小时后自动过期。要禁用此行为，将值设置为 never。

关键词类型：任务关键词。你只能将其用作 pages 任务的一部分。

支持的值：过期时间。如果未提供单位，则时间以秒为单位。也支持变量。有效值包括：

• '42'
• 42 seconds
• 3 mins 4 sec
• 2 hrs 20 min
• 2h20min
• 6 mos 1 day
• 47 yrs 6 mos and 4d
• 3 weeks and 2 days
• never
• $DURATION

pages.expire_in 示例：

yaml
1create-pages:
2  stage: deploy
3  script:
4    - echo "Pages accessible through ${CI_PAGES_URL}"
5  pages:  # 指定这是一个 Pages 任务并发布默认的 public 目录
6    expire_in: 1 week

parallel

使用 parallel 在单个流水线中并行多次运行一个任务。

必须存在多个 runner，或者单个 runner 必须配置为同时运行多个任务。

并行任务按顺序命名为 job_name 1/N 到 job_name N/N。

关键词类型：任务关键词。你只能将其用作任务的一部分。

支持的值：

• 从 1 到 200 的数值。

parallel 示例：

yaml
test:
  script: rspec
  parallel: 5

此示例创建了 5 个并行运行的任务，命名为 test 1/5 到 test 5/5。

附加细节：

• 每个并行任务都有一个 CI_NODE_INDEX 和 CI_NODE_TOTAL 预定义的 CI/CD 变量 设置。
• 带有 parallel 的流水线可能会：
  • 创建比可用 runner 更多的并行运行任务。多余的任务会被排队并标记为 pending，等待可用的 runner。
  • 创建过多任务，流水线因 job_activity_limit_exceeded 错误而失败。活动流水线中可存在的最大任务数量在实例级别限制。

相关主题：

• 并行化大型任务。

parallel:matrix

使用 parallel:matrix 在单个流水线中并行多次运行一个任务，但每个任务实例有不同的变量值。

必须存在多个 runner，或者单个 runner 必须配置为同时运行多个任务。

关键词类型：任务关键词。你只能将其用作任务的一部分。

支持的值：变量哈希数组：

• 变量名称只能使用数字、字母和下划线 (_)。
• 值必须是字符串或字符串数组。
• 排列数不能超过 200。

parallel:matrix 示例：

yaml
1deploystacks:
2  stage: deploy
3  script:
4    - bin/deploy
5  parallel:
6    matrix:
7      - PROVIDER: aws
8        STACK:
9          - monitoring
10          - app1
11          - app2
12      - PROVIDER: ovh
13        STACK: [monitoring, backup, app]
14      - PROVIDER: [gcp, vultr]
15        STACK: [data, processing]
16  environment: $PROVIDER/$STACK

该示例生成 10 个并行 deploystacks 任务，每个任务有不同的 PROVIDER 和 STACK 值：

plaintext
1deploystacks: [aws, monitoring]
2deploystacks: [aws, app1]
3deploystacks: [aws, app2]
4deploystacks: [ovh, monitoring]
5deploystacks: [ovh, backup]
6deploystacks: [ovh, app]
7deploystacks: [gcp, data]
8deploystacks: [gcp, processing]
9deploystacks: [vultr, data]
10deploystacks: [vultr, processing]

附加细节：

• parallel:matrix 任务将变量值添加到任务名称中以区分任务，但大值可能导致名称超出限制：

  • 任务名称必须在 255 个字符或更少。
  • 使用 needs 时，任务名称必须在 128 个字符或更少。

• 你不能创建具有相同变量值但不同变量名称的多个矩阵配置。任务名称是从变量值生成的，而不是变量名称，因此具有相同值的矩阵条目会生成相同的任务名称并互相覆盖。

  例如，此 test 配置会尝试创建两组相同的任务，但 OS2 版本会覆盖 OS 版本：

  yaml
  1test:
  2  parallel:
  3    matrix:
  4      - OS: [ubuntu]
  5        PROVIDER: [aws, gcp]
  6      - OS2: [ubuntu]
  7        PROVIDER: [aws, gcp]

  • 使用 !reference 标签与 parallel:matrix 时有一个已知问题。

相关主题：

• 运行一维矩阵并行任务。
• 运行触发并行任务的矩阵。
• 为每个并行矩阵任务选择不同的 runner 标签。

release#

使用 release 来创建 版本。

发布作业必须能够访问 release-cli，它必须位于 $PATH 中。

如果使用 Docker 执行器，可以使用极狐GitLab 容器注册表中的这个镜像：registry.gitlab.com/gitlab-org/release-cli:latest

如果使用 Shell 执行器 或类似的执行器，请在注册 runner 的服务器上安装 release-cli。

关键词类型: 作业关键词。只能作为作业的一部分使用。

支持的值: release 的子键：

• tag_name
• tag_message（可选）
• name（可选）
• description
• ref（可选）
• milestones（可选）
• released_at（可选）
• assets:links（可选）

release 关键词示例：

yaml
1release_job:
2  stage: release
3  image: registry.gitlab.com/gitlab-org/release-cli:latest
4  rules:
5    - if: $CI_COMMIT_TAG                  # 当手动创建标签时运行该作业
6  script:
7    - echo "Running the release job."
8  release:
9    tag_name: $CI_COMMIT_TAG
10    name: 'Release $CI_COMMIT_TAG'
11    description: 'Release created using the release-cli.'

此示例创建一个发布：

• 当你推送一个 Git 标签时。
• 当你在 UI 中添加一个 Git 标签时，在 代码 > 标签 中。

附加细节：

• 所有发布作业，除了触发器作业，必须包含 script 关键词。发布作业可以使用脚本命令的输出。如果不需要脚本，可以使用占位符：

  yaml
  script:
    - echo "release job"

• release 部分在 script 关键词执行之后，并在 after_script 之前执行。

• 只有当作业的主要脚本成功时，才会创建发布。

• 如果发布已经存在，它不会更新，并且包含 release 关键词的作业会失败。

相关主题：

• 使用 release 关键词的 CI/CD 示例。
• 在单个流水线中创建多个发布。
• 使用自定义 SSL CA 证书颁发机构。

release:tag_name#

必需。发布的 Git 标签。

如果项目中尚不存在该标签，则它会在发布时同时创建。新标签使用与流水线相关联的 SHA。

关键词类型: 作业关键词。只能作为作业的一部分使用。

支持的值：

• 标签名称。

支持使用 CI/CD 变量 are supported。

release:tag_name 示例：

要在项目中添加新标签时创建发布：

• 使用 $CI_COMMIT_TAG CI/CD 变量作为 tag_name。
• 使用 rules:if 配置作业，仅在新标签时运行。

yaml
1job:
2  script: echo "Running the release job for the new tag."
3  release:
4    tag_name: $CI_COMMIT_TAG
5    description: 'Release description'
6  rules:
7    - if: $CI_COMMIT_TAG

要同时创建发布和新标签，你的 rules 不应该配置作业仅在新标签时运行。语义版本示例：

yaml
1job:
2  script: echo "Running the release job and creating a new tag."
3  release:
4    tag_name: ${MAJOR}_${MINOR}_${REVISION}
5    description: 'Release description'
6  rules:
7    - if: $CI_PIPELINE_SOURCE == "schedule"

release:tag_message#

如果标签不存在，新创建的标签将使用 tag_message 指定的消息进行注释。如果省略，则创建轻量级标签。

关键词类型: 作业关键词。只能作为作业的一部分使用。

支持的值：

• 文本字符串。

release:tag_message 示例：

yaml
1  release_job:
2    stage: release
3    release:
4      tag_name: $CI_COMMIT_TAG
5      description: 'Release description'
6      tag_message: 'Annotated tag message'

release:name#

发布名称。如果省略，则使用 release: tag_name 的值填充。

关键词类型: 作业关键词。只能作为作业的一部分使用。

支持的值：

• 文本字符串。

release:name 示例：

yaml
  release_job:
    stage: release
    release:
      name: 'Release $CI_COMMIT_TAG'

release:description#

发布的长描述。

关键词类型: 作业关键词。只能作为作业的一部分使用。

支持的值：

• 带有长描述的字符串。
• 包含描述的文件路径。
  • 文件位置必须相对于项目目录 ($CI_PROJECT_DIR)。
  • 如果文件是符号链接，则它必须位于 $CI_PROJECT_DIR 中。
  • ./path/to/file 和文件名不能包含空格。

release:description 示例：

yaml
job:
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: './path/to/CHANGELOG.md'

附加细节：

• description 由运行 release-cli 的 shell 评估。你可以使用 CI/CD 变量来定义描述，但某些 shell 使用不同的语法来引用变量。同样，某些 shell 可能需要特殊字符进行转义。例如，反引号（`）可能需要使用反斜杠 (\) 进行转义。

release:ref#

发布的 ref，如果 release: tag_name 尚不存在。

关键词类型: 作业关键词。只能作为作业的一部分使用。

支持的值：

• 提交 SHA、另一个标签名称或分支名称。

release:milestones#

发布所关联的每个里程碑的标题。

release:released_at#

发布准备好的日期和时间。

支持的值：

• 用引号括起来并以 ISO 8601 格式表示的日期。

release:released_at 示例：

yaml
released_at: '2021-03-15T08:00:00Z'

附加细节：

• 如果未定义，则使用当前日期和时间。

release:assets:links#

使用 release:assets:links 在发布中包含 资产链接。

需要 release-cli 版本 v0.4.0 或更高。

release:assets:links 示例：

yaml
1assets:
2  links:
3    - name: 'asset1'
4      url: 'https://example.com/assets/1'
5    - name: 'asset2'
6      url: 'https://example.com/assets/2'
7      filepath: '/pretty/url/1' # 可选
8      link_type: 'other' # 可选

resource_group#

使用 resource_group 来创建一个 资源组，确保同一项目的不同流水线之间的作业互斥。

例如，如果属于同一资源组的多个作业同时排队，则只有一个作业开始。其他作业会等待 resource_group 释放。

资源组的行为类似于其他编程语言中的信号量。

你可以选择一种 处理模式 来策略性地控制作业并发，以满足你的部署偏好。默认处理模式是 unordered。要更改资源组的处理模式，请使用 API 发送请求以编辑现有资源组。

你可以为每个环境定义多个资源组。例如，在部署到物理设备时，可能有多个物理设备。每个设备可以进行部署，但在任何给定时间只能发生一个设备的部署。

关键词类型: 作业关键词。只能作为作业的一部分使用。

支持的值：

• 仅字母、数字、-、_、/、$、{、}、. 和空格。不能以 / 开头或结尾。使用 CI/CD 变量 是受支持的。

resource_group 示例：

yaml
deploy-to-production:
  script: deploy
  resource_group: production

在此示例中，两个独立流水线中的 deploy-to-production 作业绝不会同时运行。因此，可以确保不会发生并发部署到生产环境。

相关主题：

• 使用跨项目/父子流水线进行流水线级并发控制。

retry#

使用 retry 来配置作业失败时重试的次数。如果未定义，默认为 0，作业不重试。

当作业失败时，作业最多处理两次，直到成功或达到最大重试次数。

默认情况下，所有失败类型都会导致作业重试。使用 retry:when 或 retry:exit_codes 来选择重试的失败类型。

关键词类型: 作业关键词。只能作为作业的一部分使用或在 default 部分 中使用。

支持的值：

• 0（默认）、1 或 2。

retry 示例：

yaml
1test:
2  script: rspec
3  retry: 2
4
5test_advanced:
6  script:
7    - echo "Run a script that results in exit code 137."
8    - exit 137
9  retry:
10    max: 2
11    when: runner_system_failure
12    exit_codes: 137

如果退出码是 137 或发生 runner 系统故障，test_advanced 将最多重试 2 次。

retry:when#

使用 retry:when 和 retry:max 来仅针对特定失败情况重试作业。retry:max 是最大重试次数，类似于 retry，可以是 0、1 或 2。

关键词类型: 作业关键词。只能作为作业的一部分使用或在 default 部分 中使用。

支持的值：

• 单个失败类型或一个或多个失败类型的数组：

• always：在任何失败时重试（默认）。
• unknown_failure：当失败原因未知时重试。
• script_failure：当脚本失败时重试。
  • runner 无法拉取 Docker 镜像时重试。对于 docker、docker+machine、kubernetes 执行器。
• api_failure：在 API 失败时重试。
• stuck_or_timeout_failure：当作业卡住或超时时重试。
• runner_system_failure：如果发生 runner 系统故障（例如作业设置失败）时重试。
• runner_unsupported：如果 runner 不受支持时重试。
• stale_schedule：如果延迟作业无法执行时重试。
• job_execution_timeout：如果脚本超过为作业设置的最大执行时间时重试。
• archived_failure：如果作业已归档且无法运行时重试。
• unmet_prerequisites：如果作业未能完成前置任务时重试。
• scheduler_failure：如果调度程序无法将作业分配给 runner 时重试。
• data_integrity_failure：如果存在未知作业问题时重试。

retry:when 示例（单个失败类型）：

yaml
test:
  script: rspec
  retry:
    max: 2
    when: runner_system_failure

如果发生除 runner 系统故障以外的失败，作业不重试。

retry:when 示例（失败类型数组）：

yaml
1test:
2  script: rspec
3  retry:
4    max: 2
5    when:
6      - runner_system_failure
7      - stuck_or_timeout_failure

retry:exit_codes#

使用 retry:exit_codes 和 retry:max 来仅针对特定失败情况重试作业。retry:max 是最大重试次数，类似于 retry，可以是 0、1 或 2。

关键词类型: 作业关键词。只能作为作业的一部分使用或在 default 部分 中使用。

支持的值：

• 单个退出码。
• 退出码数组。

retry:exit_codes 示例：

yaml
1test_job_1:
2  script:
3    - echo "Run a script that results in exit code 1. This job isn't retried."
4    - exit 1
5  retry:
6    max: 2
7    exit_codes: 137
8
9test_job_2:
10  script:
11    - echo "Run a script that results in exit code 137. This job will be retried."
12    - exit 137
13  retry:
14    max: 1
15    exit_codes:
16      - 255
17      - 137

相关主题：

你可以使用变量指定某些作业执行阶段的 重试尝试次数。

rules#

使用 rules 来在流水线中包含或排除作业。

规则在创建流水线时进行评估，并按顺序评估。当找到匹配项时，不再检查其他规则，并根据配置将作业包含或排除在流水线中。如果没有规则匹配，则作业不添加到流水线中。

rules 接受一个规则数组。每个规则必须至少有一个：

• if
• changes
• exists
• when

规则还可以选择性地与以下内容组合：

• allow_failure
• needs
• variables
• interruptible

你可以将多个关键词组合在一起以实现 复杂规则。

作业被添加到流水线中：

• 如果 if、changes 或 exists 规则匹配，并配置为 when: on_success（如果未定义则默认为），when: delayed 或 when: always。
• 如果规则仅 when: on_success、when: delayed 或 when: always。

作业不被添加到流水线中：

• 如果没有规则匹配。
• 如果规则匹配并且具有 when: never。

有关其他示例，请参阅 使用 rules 指定作业运行时间。

rules:if#

使用 rules:if 子句来指定何时将作业添加到流水线中：

• 如果 if 语句为真，将作业添加到流水线中。
• 如果 if 语句为真，但与 when: never 组合，不将作业添加到流水线中。
• 如果 if 语句为假，检查下一个 rules 项（如果还有更多存在）。

if 子句根据 CI/CD 变量 或 预定义 CI/CD 变量 的值进行评估，但有一些例外。

关键词类型: 作业特定和流水线特定。你可以将其作为作业的一部分来配置作业行为，或使用 workflow 来配置流水线行为。

支持的值：

• CI/CD 变量表达式。

rules:if 示例：

yaml
1job:
2  script: echo "Hello, Rules!"
3  rules:
4    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH
5      when: never
6    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/
7      when: manual
8      allow_failure: true
9    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME

附加细节：

• 不能在 if 中使用 嵌套变量。
• 如果规则匹配且未定义 when，则规则使用为作业定义的 when，如果未定义则默认为 on_success。
• 可以在作业级别与规则中的 when 混合使用 when。规则中的 when 配置优先于作业级别的 when。
• 与 script 部分中的变量不同，规则表达式中的变量始终格式化为 $VARIABLE。
  • 可以将 rules:if 与 include 一起使用以有条件地包含其他配置文件。
• CI/CD 变量在 =~ 和 !~ 表达式的右侧作为正则表达式进行评估。

相关主题：

• 用于 rules 的常见 if 表达式。
• 避免重复的流水线。
• 使用 rules 运行合并请求流水线。

规则：更改#

使用 rules:changes 来指定在检查特定文件的更改时何时将作业添加到流水线中。

对于新的分支流水线或者没有 Git push 事件时，rules:changes 总是评估为 true，并且作业总是运行。诸如标签流水线、计划流水线和手动流水线等，都没有关联的 Git push 事件。为了覆盖这些情况，使用 rules:changes:compare_to 来指定与流水线 ref 比较的分支。

如果不使用 compare_to，您应该仅在 分支流水线 或 合并请求流水线 中使用 rules:changes，尽管在创建新分支时 rules:changes 仍然评估为 true。对于：

• 合并请求流水线，rules:changes 将更改与目标 MR 分支进行比较。
• 分支流水线，rules:changes 将更改与分支上的前一个提交进行比较。

关键字类型：作业关键字。您只能在作业中使用它。

支持的值：

一个数组，包括任意数量的：

• 文件路径。文件路径可以包含 CI/CD 变量。
• 通配路径：
  • 单个目录，例如 path/to/directory/*。
  • 一个目录及其所有子目录，例如 path/to/directory/**/*。
• 所有文件具有相同扩展名或多个扩展名的通配 glob 路径，例如 *.md 或 path/to/directory/*.{rb,py,sh}。
• 根目录或所有目录中的文件的通配路径，用双引号括起来。例如 "*.json" 或 "**/*.json"。

rules:changes 示例：

yaml
1docker build:
2  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
3  rules:
4    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
5      changes:
6        - Dockerfile
7      when: manual
8      allow_failure: true
9
10docker build alternative:
11  variables:
12    DOCKERFILES_DIR: 'path/to/dockerfiles'
13  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
14  rules:
15    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
16      changes:
17        - $DOCKERFILES_DIR/**/*

在这个例子中：

• 如果流水线是合并请求流水线，检查 Dockerfile 和 $DOCKERFILES_DIR/**/* 中的文件是否有更改。
• 如果 Dockerfile 已更改，将作业添加到流水线中作为手动作业，即使作业未触发，流水线也会继续运行（allow_failure: true）。
• 如果 $DOCKERFILES_DIR/**/* 中的文件已更改，将作业添加到流水线中。
• 如果没有列出的文件发生更改，则不会将任何作业添加到任何流水线（与 when: never 相同）。

附加详情：

• Glob 模式使用 Ruby 的 File.fnmatch 进行解释，使用标志 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB。
• 每个 rules:changes 部分最多可以定义 50 个模式或文件路径。
• 如果任何匹配的文件发生更改，changes 解析为 true（OR 操作）。
• 有关其他示例，请参见 使用 rules 指定作业运行时机。
• 您可以同时用于变量和路径的 $ 字符。例如，如果 $VAR 变量存在，则使用其值。如果不存在，则将 $ 解释为路径的一部分。

相关主题：

• 使用 rules: changes 时，作业或流水线可能会意外运行。

规则：更改：路径#

使用 rules:changes 来指定只有在特定文件更改时才添加作业到流水线，并使用 rules:changes:paths 来指定文件。

rules:changes:paths 与不使用任何子键的 rules:changes 相同。所有附加详细信息和相关主题都相同。

关键字类型：作业关键字。您只能在作业中使用它。

支持的值：

• 与上面的 rules:changes 相同。

rules:changes:paths 示例：

yaml
1docker-build-1:
2  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
3  rules:
4    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
5      changes:
6        - Dockerfile
7
8docker-build-2:
9  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
10  rules:
11    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
12      changes:
13        paths:
14          - Dockerfile

在这个例子中，两个作业具有相同的行为。

规则：更改：比较到#

使用 rules:changes:compare_to 指定要比较的 ref，以检查在 rules:changes:paths 下列出的文件的更改。

关键字类型：作业关键字。您只能在作业中使用它，且必须与 rules:changes:paths 结合使用。

支持的值：

• 分支名称，如 main、branch1 或 refs/heads/branch1。
• 标签名称，如 tag1 或 refs/tags/tag1。
• 提交 SHA，如 2fg31ga14b。

支持 CI/CD 变量。

rules:changes:compare_to 示例：

yaml
1docker build:
2  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
3  rules:
4    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
5      changes:
6        paths:
7          - Dockerfile
8        compare_to: 'refs/heads/branch1'

在这个例子中，只有在 Dockerfile 相对于 refs/heads/branch1 发生更改并且流水线来源是合并请求事件时才包含 docker build 作业。

附加详情：

• 在使用 合并结果流水线 时使用 compare_to 可能会导致意外结果，因为比较基础是极狐GitLab 创建的内部提交。

相关主题：

• 您可以使用 rules:changes:compare_to 来 跳过作业，如果分支为空。

规则：存在#

使用 exists 来在存储库中存在某些文件时运行作业。

关键字类型：作业关键字。您可以在作业或 include 中使用它。

支持的值：

• 文件路径数组。路径相对于项目目录（$CI_PROJECT_DIR），不能直接链接到外部。文件路径可以使用 glob 模式和 CI/CD 变量。

rules:exists 示例：

yaml
1job:
2  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
3  rules:
4    - exists:
5        - Dockerfile
6
7job2:
8  variables:
9    DOCKERPATH: "**/Dockerfile"
10  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
11  rules:
12    - exists:
13        - $DOCKERPATH

在这个例子中：

• job1 如果存储库的根目录中存在 Dockerfile，则运行。
• job2 如果存储库中的任何位置存在 Dockerfile，则运行。

附加详情：

• Glob 模式使用 Ruby 的 File.fnmatch 进行解释，使用标志 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB。
• 出于性能原因，极狐GitLab 对 exists 模式或文件路径最多执行 50,000 次检查。在第 50,000 次检查后，具有模式 glob 的规则始终匹配。换句话说，exists 规则在项目文件超过 50,000 个时总是假定匹配，或者如果文件少于 50,000 个但 exists 规则检查超过 50,000 次。
  • 如果有多个模式 glob，限制是 50,000 除以模式 glob 的数量。例如，一个具有 5 个模式 glob 的规则的文件限制为 10,000。
• 每个 rules:exists 部分最多可以定义 50 个模式或文件路径。
• 如果找到任何列出的文件，exists 解析为 true（OR 操作）。
• 使用作业级别 rules:exists 时，极狐GitLab 在运行流水线的项目和 ref 中搜索文件。当使用 include 与 rules:exists 时，极狐GitLab 在包含 include 部分的文件的项目和 ref 中搜索文件。当使用以下功能时，包含 include 部分的项目可能与运行流水线的项目不同：
  • 嵌套包含。
  • 合规流水线。
• rules:exists 不能搜索 产物 的存在，因为 rules 评估发生在作业运行和获取产物之前。

rules:exists:paths#

rules:exists:paths 与使用 rules:exists 没有任何子键时相同。所有附加细节相同。

关键字类型: 作业关键字。您可以将其作为作业或 include 的一部分使用。

支持的值:

• 文件路径数组。

rules:exists:paths 示例:

yaml
1docker-build-1:
2  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
3  rules:
4    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
5      exists:
6        - Dockerfile
7
8docker-build-2:
9  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
10  rules:
11    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
12      exists:
13        paths:
14          - Dockerfile

在这个示例中，两个作业的行为相同。

附加细节:

• 在某些情况下，您不能在 CI/CD 变量中使用 / 或 ./ 与 exists 一起使用。

rules:exists:project#

使用 rules:exists:project 来指定要搜索 rules:exists:paths 下列出的文件的位置。必须与 rules:exists:paths 一起使用。

关键字类型: 作业关键字。您可以将其作为作业或 include 的一部分使用，并且必须与 rules:exists:paths 结合使用。

支持的值:

• exists:project: 完整的项目路径，包括命名空间和群组。
• exists:ref: 可选。用于搜索文件的提交引用。引用可以是标签、分支名或 SHA。在未指定时默认使用项目的 HEAD。

rules:exists:project 示例:

yaml
1docker build:
2  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
3  rules:
4    - exists:
5        paths:
6          - Dockerfile
7        project: my-group/my-project
8        ref: v1.0.0

在此示例中，只有在项目 my-group/my-project 上标记为 v1.0.0 的提交中存在 Dockerfile 时才会包含 docker build 作业。

rules:when#

使用 rules:when 单独或作为其他规则的一部分来控制将作业添加到流水线的条件。rules:when 类似于 when，但输入选项稍有不同。

如果 rules:when 规则未与 if、changes 或 exists 结合使用，则在评估作业规则时始终匹配。

关键字类型: 作业特定。您只能将其作为作业的一部分使用。

支持的值:

• on_success (默认): 仅在早期阶段没有作业失败时运行作业。
• on_failure: 仅在早期阶段至少有一个作业失败时运行作业。
• never: 无论早期阶段作业的状态如何，都不运行作业。
• always: 无论早期阶段作业的状态如何，都运行作业。
• manual: 将作业添加到流水线作为手动作业。 allow_failure 的默认值更改为 false。
• delayed: 将作业添加到流水线作为延迟作业。

rules:when 示例:

yaml
1job1:
2  rules:
3    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
4    - if: $CI_COMMIT_REF_NAME =~ /feature/
5      when: delayed
6    - when: manual
7  script:
8    - echo

在这个示例中，job1 被添加到流水线中:

• 对于默认分支，使用 when: on_success，这是未定义 when 时的默认行为。
• 对于功能分支作为延迟作业。
• 在所有其他情况下作为手动作业。

附加细节:

• 在评估 on_success 和 on_failure 作业状态时:
  • 在早期阶段具有 allow_failure: true 的作业即使失败也被认为是成功的。
  • 早期阶段被跳过的作业，例如尚未启动的手动作业， 被认为是成功的。
• 使用 rules:when: manual 添加手动作业时:
  • allow_failure 默认变为 false。此默认值与使用 when: manual 添加手动作业的情况相反。
  • 要实现与在 rules 外部定义的 when: manual 相同的行为，请将 rules: allow_failure 设置为 true。

rules:allow_failure#

使用 allow_failure: true 在 rules 中允许作业失败而不停止流水线。

您还可以将 allow_failure: true 与手动作业一起使用。流水线继续运行而不等待手动作业的结果。与 when: manual 在规则中结合使用的 allow_failure: false 会导致流水线在继续之前等待手动作业运行。

关键字类型: 作业关键字。您只能将其作为作业的一部分使用。

支持的值:

• true 或 false。如果未定义，默认值为 false。

rules:allow_failure 示例:

yaml
1job:
2  script: echo "Hello, Rules!"
3  rules:
4    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
5      when: manual
6      allow_failure: true

如果规则匹配，那么作业是一个具有 allow_failure: true 的手动作业。

附加细节:

• 规则级别的 rules:allow_failure 会覆盖作业级别的 allow_failure， 并且仅在特定规则触发作业时适用。

rules:needs#

在规则中使用 needs 来更新作业的 needs 以满足特定条件。当条件匹配规则时，作业的 needs 配置将完全替换为规则中的 needs。

关键字类型: 作业特定。您只能将其作为作业的一部分使用。

支持的值:

• 作业名称字符串数组。
• 带有作业名称的哈希，可选地附加其他属性。
• 空数组 ([])，以在满足特定条件时将作业需求设置为无。

rules:needs 示例:

yaml
1build-dev:
2  stage: build
3  rules:
4    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
5  script: echo "Feature branch, so building dev version..."
6
7build-prod:
8  stage: build
9  rules:
10    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
11  script: echo "Default branch, so building prod version..."
12
13tests:
14  stage: test
15  rules:
16    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
17      needs: ['build-dev']
18    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
19      needs: ['build-prod']
20  script: echo "Running dev specs by default, or prod specs when default branch..."

在这个示例中:

• 如果流水线在不是默认分支的分支上运行，因此规则匹配第一个条件，则 specs 作业需要 build-dev 作业。
• 如果流水线在默认分支上运行，因此规则匹配第二个条件，则 specs 作业需要 build-prod 作业。

附加细节:

• 规则中的 needs 会覆盖在作业级别定义的任何 needs。被覆盖时，其行为与作业级别的 needs相同。
• 规则中的 needs 可以接受 产物 和 可选。

rules:variables#

使用 variables 在 rules 中定义特定条件的变量。

关键字类型: 作业特定。您只能将其作为作业的一部分使用。

支持的值:

• 格式为 VARIABLE-NAME: value 的变量哈希。

rules:variables 示例:

yaml
1job:
2  variables:
3    DEPLOY_VARIABLE: "default-deploy"
4  rules:
5    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
6      variables:                              # Override DEPLOY_VARIABLE defined
7        DEPLOY_VARIABLE: "deploy-production"  # at the job level.
8    - if: $CI_COMMIT_REF_NAME =~ /feature/
9      variables:
10        IS_A_FEATURE: "true"                  # Define a new variable.
11  script:
12    - echo "Run script with $DEPLOY_VARIABLE as an argument"
13    - echo "Run another script if $IS_A_FEATURE exists"

rules:interruptible#

在规则中使用 interruptible 来更新作业的 interruptible 值以满足特定条件。

关键字类型: 作业特定。您只能将其作为作业的一部分使用。

支持的值:

• true 或 false。

rules:interruptible 示例:

yaml
1job:
2  script: echo "Hello, Rules!"
3  interruptible: true
4  rules:
5    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
6      interruptible: false  # Override interruptible defined at the job level.
7    - when: on_success

附加细节:

• 规则级别的 rules:interruptible 会覆盖作业级别的 interruptible， 并且仅在特定规则触发作业时适用。

run#

使用 run 来定义一系列在作业中执行的步骤。每个步骤可以是脚本或预定义步骤。

您还可以提供可选的环境变量和输入。

关键字类型: 作业关键字。您只能将其作为作业的一部分使用。

支持的值:

• 哈希数组，其中每个哈希表示一个步骤，具有以下可能的键:
  • name: 表示步骤名称的字符串。
  • script: 包含要执行的 shell 命令的字符串或字符串数组。
  • step: 标识要运行的预定义步骤的字符串。
  • env: 可选。特定于此步骤的环境变量哈希。
  • inputs: 可选。预定义步骤的输入参数哈希。

每个数组条目必须有一个 name，并且一个 script 或 step (但不能同时具有)。

run 示例:

yaml
1job:
2  run:
3    - name: 'hello_steps'
4      script: 'echo "hello from step1"'
5    - name: 'bye_steps'
6      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@main
7      inputs:
8        echo: 'bye steps!'
9      env:
10        var1: 'value 1'

在这个示例中，作业有两个步骤:

• hello_steps 运行 echo shell 命令。
• bye_steps 使用预定义步骤，带有环境变量和输入参数。

附加细节:

• 一个步骤可以具有 script 或 step 键，但不能同时具有。
• run 配置不能与现有的 script 关键字一起使用。
• 可以使用 YAML 块标量语法 定义多行脚本。

script#

使用 script 指定要由 runner 执行的命令。

所有作业除了触发作业都需要一个 script 关键字。

关键字类型: 作业关键字。您只能将其作为作业的一部分使用。

支持的值: 包含以下内容的数组:

• 单行命令。
• 分割为多行的长命令。
• YAML 锚点。

支持CI/CD 变量。

script 示例:

yaml
1job1:
2  script: "bundle exec rspec"
3
4job2:
5  script:
6    - uname -a
7    - bundle exec rspec

附加细节:

• 当您在 script 中使用这些特殊字符时，必须使用单引号 (') 或双引号 (")。

相关主题:

• 您可以忽略非零退出代码。
• 使用颜色代码与 script 使作业日志更易于审阅。
• 创建自定义可折叠部分 以简化作业日志输出。

secrets#

使用 secrets 指定 CI/CD 密钥以:

• 从外部密钥提供者检索。
• 在作业中作为 CI/CD 变量 (默认使用 file 类型)。

secrets:vault#

使用 secrets:vault 指定由 HashiCorp Vault 提供的密钥。

关键字类型: 作业关键字。您只能将其作为作业的一部分使用。

支持的值:

• engine:name: 密钥引擎的名称。可以是 kv-v2 (默认)、kv-v1 或 generic。
• engine:path: 密钥引擎的路径。
• path: 密钥的路径。
• field: 存储密码的字段名称。

secrets:vault 示例:

要明确指定所有细节并使用 KV-V2 密钥引擎:

yaml
1job:
2  secrets:
3    DATABASE_PASSWORD:  # 将密钥路径存储在此 CI/CD 变量中
4      vault:  # 转换为密钥: `ops/data/production/db`, 字段: `password`
5        engine:
6          name: kv-v2
7          path: ops
8        path: production/db
9        field: password

您可以简化此语法。在简写语法中，engine:name 和 engine:path 均默认为 kv-v2:

yaml
job:
  secrets:
    DATABASE_PASSWORD:  # 将密钥路径存储在此 CI/CD 变量中
      vault: production/db/password  # 转换为密钥: `kv-v2/data/production/db`, 字段: `password`

要在简写语法中指定自定义密钥引擎路径，请添加以 @ 开头的后缀:

yaml
job:
  secrets:
    DATABASE_PASSWORD:  # 将密钥路径存储在此 CI/CD 变量中
      vault: production/db/password@ops  # 转换为密钥: `ops/data/production/db`, 字段: `password`

secrets:gcp_secret_manager#

使用 secrets:gcp_secret_manager 来指定由 GCP Secret Manager 提供的机密。

关键词类型: 作业关键词。您只能作为作业的一部分使用它。

支持的值：

• name: 机密的名称。
• version: 机密的版本。

secrets:gcp_secret_manager 示例：

yaml
1job:
2  secrets:
3    DATABASE_PASSWORD:
4      gcp_secret_manager:
5        name: 'test'
6        version: 2

相关主题：

• 在极狐GitLab CI/CD 中使用 GCP Secret Manager 机密。

secrets:azure_key_vault#

使用 secrets:azure_key_vault 来指定由 Azure Key Vault 提供的机密。

关键词类型: 作业关键词。您只能作为作业的一部分使用它。

支持的值：

• name: 机密的名称。
• version: 机密的版本。

secrets:azure_key_vault 示例：

yaml
1job:
2  secrets:
3    DATABASE_PASSWORD:
4      azure_key_vault:
5        name: 'test'
6        version: 'test'

相关主题：

• 在极狐GitLab CI/CD 中使用 Azure Key Vault 机密。

secrets:file#

使用 secrets:file 来配置机密以存储为 file 或 variable 类型的 CI/CD 变量。

默认情况下，机密以 file 类型的 CI/CD 变量传递给作业。机密的值存储在文件中，变量包含文件的路径。

如果您的软件不能使用 file 类型的 CI/CD 变量，请设置 file: false 以将机密值直接存储在变量中。

关键词类型: 作业关键词。您只能作为作业的一部分使用它。

支持的值：

• true（默认）或 false。

secrets:file 示例：

yaml
job:
  secrets:
    DATABASE_PASSWORD:
      vault: production/db/password@ops
      file: false

其他细节：

• file 关键词是 CI/CD 变量的设置，必须嵌套在 CI/CD 变量名称下，而不是在 vault 部分中。

secrets:token#

使用 secrets:token 明确选择一个令牌，通过引用令牌的 CI/CD 变量来与外部机密提供程序进行身份验证。

关键词类型: 作业关键词。您只能作为作业的一部分使用它。

支持的值：

• ID 令牌的名称

secrets:token 示例：

yaml
1job:
2  id_tokens:
3    AWS_TOKEN:
4      aud: https://aws.example.com
5    VAULT_TOKEN:
6      aud: https://vault.example.com
7  secrets:
8    DB_PASSWORD:
9      vault: gitlab/production/db
10      token: $VAULT_TOKEN

其他细节：

• 当未设置 token 关键词且仅定义了一个令牌时，定义的令牌将自动使用。
• 如果定义了多个令牌，应通过设置 token 关键词来指定使用哪个令牌。如果未指定使用哪个令牌，则无法预测每次作业运行时使用哪个令牌。

services#

使用 services 来指定脚本运行成功所需的任何其他 Docker 镜像。services 镜像 与 image 关键词中指定的镜像链接。

关键词类型: 作业关键词。您只能作为作业的一部分或在 default 部分中使用它。

支持的值: 服务镜像的名称，包括所需的注册表路径，可以是以下格式之一：

• <image-name>（与使用 <image-name> 和 latest 标签相同）
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD 变量受到支持，但alias 不支持。

services 示例：

yaml
1default:
2  image:
3    name: ruby:2.6
4    entrypoint: ["/bin/bash"]
5
6  services:
7    - name: my-postgres:11.7
8      alias: db-postgres
9      entrypoint: ["/usr/local/bin/db-postgres"]
10      command: ["start"]
11
12  before_script:
13    - bundle install
14
15test:
16  script:
17    - bundle exec rake spec

在此示例中，极狐GitLab 为作业启动了两个容器：

• 运行 script 命令的 Ruby 容器。
• PostgreSQL 容器。Ruby 容器中的 script 命令可以连接到 PostgreSQL 数据库，地址为 db-postgres 主机名。

相关主题：

• services 的可用设置。
• 在 .gitlab-ci.yml 文件中定义 services。
• 在 Docker 容器中运行 CI/CD 作业。
• 使用 Docker 构建 Docker 镜像。

services:docker#

使用 services:docker 向极狐GitLab Runner 的 Docker 执行器传递选项。

关键词类型: 作业关键词。您只能作为作业的一部分或在 default 部分中使用它。

支持的值：

Docker 执行器的选项哈希，可以包括：

• platform: 选择要拉取的镜像的架构。如果未指定，默认与主机 runner 的平台相同。
• user: 指定运行容器时使用的用户名或 UID。

services:docker 示例：

yaml
1arm-sql-job:
2  script: echo "Run sql tests in service container"
3  image: ruby:2.6
4  services:
5    - name: super/sql:experimental
6      docker:
7        platform: arm64/v8
8        user: dave

其他细节：

• services:docker:platform 映射到 docker pull --platform 选项。
• services:docker:user 映射到 docker run --user 选项。

services:pull_policy#

runner 用于获取 Docker 镜像的拉取策略。

关键词类型: 作业关键词。您只能作为作业的一部分或在 default 部分中使用它。

支持的值：

• 单一拉取策略，或在数组中使用多个拉取策略。可以是 always、if-not-present 或 never。

services:pull_policy 示例：

yaml
1job1:
2  script: echo "A single pull policy."
3  services:
4    - name: postgres:11.6
5      pull_policy: if-not-present
6
7job2:
8  script: echo "Multiple pull policies."
9  services:
10    - name: postgres:11.6
11      pull_policy: [always, if-not-present]

其他细节：

• 如果 runner 不支持定义的拉取策略，作业将失败，并出现类似于以下的错误： ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never])。

相关主题：

• 在 Docker 容器中运行 CI/CD 作业。
• 配置 runner 如何拉取镜像。
• 设置多个拉取策略。

stage#

使用 stage 来定义作业运行的 阶段。同一 stage 中的作业可以并行执行（请参见 其他细节）。

如果未定义 stage，则作业默认使用 test 阶段。

关键词类型: 作业关键词。您只能作为作业的一部分使用它。

支持的值：字符串，可以是：

• 默认阶段。
• 用户定义的阶段。

stage 示例：

yaml
1stages:
2  - build
3  - test
4  - deploy
5
6job1:
7  stage: build
8  script:
9    - echo "This job compiles code."
10
11job2:
12  stage: test
13  script:
14    - echo "This job tests the compiled code. It runs when the build stage completes."
15
16job3:
17  script:
18    - echo "This job also runs in the test stage".
19
20job4:
21  stage: deploy
22  script:
23    - echo "This job deploys the code. It runs when the test stage completes."
24  environment: production

其他细节：

• 阶段名称必须少于 255 个字符。
• 如果作业在不同的 runner 上运行，则可以并行运行。
• 如果您只有一个 runner，作业可以并行运行，如果 runner 的 concurrent 设置 大于 1。

stage: .pre#

使用 .pre 阶段使作业在流水线开始时运行。默认情况下，.pre 是流水线中的第一个阶段。用户定义的阶段在 .pre 之后执行。 您不必在 stages 中定义 .pre。

如果流水线仅包含 .pre 或 .post 阶段的作业，则不会运行。必须至少有一个其他阶段的作业。

关键词类型: 您只能将其与作业的 stage 关键词一起使用。

stage: .pre 示例：

yaml
1stages:
2  - build
3  - test
4
5job1:
6  stage: build
7  script:
8    - echo "This job runs in the build stage."
9
10first-job:
11  stage: .pre
12  script:
13    - echo "This job runs in the .pre stage, before all other stages."
14
15job2:
16  stage: test
17  script:
18    - echo "This job runs in the test stage."

其他细节：

• 如果流水线中有带有 needs: [] 的作业和 .pre 阶段的作业，它们将在流水线创建后立即启动。带有 needs: [] 的作业立即启动，忽略任何阶段配置。
• 流水线执行策略 可以定义 .pipeline-policy-pre 阶段，该阶段在 .pre 之前运行。

stage: .post#

使用 .post 阶段使作业在流水线结束时运行。默认情况下，.post 是流水线中的最后一个阶段。用户定义的阶段在 .post 之前执行。 您不必在 stages 中定义 .post。

如果流水线仅包含 .pre 或 .post 阶段的作业，则不会运行。必须至少有一个其他阶段的作业。

关键词类型: 您只能将其与作业的 stage 关键词一起使用。

stage: .post 示例：

yaml
1stages:
2  - build
3  - test
4
5job1:
6  stage: build
7  script:
8    - echo "This job runs in the build stage."
9
10last-job:
11  stage: .post
12  script:
13    - echo "This job runs in the .post stage, after all other stages."
14
15job2:
16  stage: test
17  script:
18    - echo "This job runs in the test stage."

其他细节：

• 流水线执行策略 可以定义 .pipeline-policy-post 阶段，该阶段在 .post 之后运行。

tags#

使用 tags 从项目可用的所有 runner 列表中选择特定的 runner。

当您注册 runner 时，可以指定 runner 的标签，例如 ruby、postgres 或 development。要拾取并运行作业，runner 必须被分配作业中列出的每个标签。

关键词类型: 作业关键词。您只能作为作业的一部分或在 default 部分中使用它。

支持的值：

• 标签名称的数组，区分大小写。
• CI/CD 变量 受到支持。

tags 示例：

yaml
job:
  tags:
    - ruby
    - postgres

在此示例中，只有 同时 具有 ruby 和 postgres 标签的 runner 才能运行作业。

其他细节：

• 标签数量必须少于 50。

相关主题：

• 使用标签控制 runner 可以运行的作业
• 为每个并行矩阵作业选择不同的 runner 标签
• 托管 runner 的 runner 标签：
  • Linux 上的托管 runner
  • 支持 GPU 的托管 runner
  • macOS 上的托管 runner
  • Windows 上的托管 runner

timeout#

使用 timeout 为特定作业配置超时。如果作业运行时间超过超时，作业将失败。

作业级别的超时可以长于 项目级别的超时，但不能长于 runner 的超时。

关键词类型: 作业关键词。您只能作为作业的一部分或在 default 部分中使用它。

支持的值：用自然语言书写的一段时间。例如，这些都是等价的：

• 3600 秒
• 60 分钟
• 一小时

timeout 示例：

yaml
1build:
2  script: build.sh
3  timeout: 3 小时 30 分钟
4
5test:
6  script: rspec
7  timeout: 3h 30m

trigger#

使用 trigger 声明作业是一个“触发作业”，启动一个下游流水线，它可以是：

• 多项目流水线。
• 子流水线。

触发作业只能使用有限的极狐GitLab CI/CD 配置关键词。触发作业中可用的关键词为：

• allow_failure。
• extends。
• needs，但不包括 needs:project。
• only 和 except。
• parallel。
• rules。
• stage。
• trigger。
• variables。
• when（仅限 on_success、on_failure 或 always 值）。
• resource_group。
• environment。

关键词类型: 作业关键词。您只能作为作业的一部分使用它。

支持的值：

• 对于多项目流水线，下游项目的路径。极狐GitLab 15.3 及更高版本支持 CI/CD 变量 受支持，但不支持 仅作业变量。或者，使用 trigger:project。
• 对于子流水线，使用 trigger:include。

trigger 示例：

yaml
trigger-multi-project-pipeline:
  trigger: my-group/my-project

其他细节：

• 您可以在与 trigger 同一作业中使用 when:manual，但无法使用 API 启动 when:manual 触发作业。有关更多详细信息，请参阅 问题 284086。
• 在运行手动触发作业之前，您不能手动指定 CI/CD 变量。
• 在顶层 variables 部分（全局）或触发作业中定义的 CI/CD 变量 将作为 触发变量 转发到下游流水线。
• 默认情况下，流水线变量 不会传递到下游流水线。使用 trigger:forward 将这些变量转发到下游流水线。
• 仅作业变量 在触发作业中不可用。
• 在 runner 的 config.toml 中定义的环境变量 在触发作业中不可用，也不会传递到下游流水线。
• 您不能在触发作业中使用 needs:pipeline:job。

相关主题：

• 多项目流水线配置示例。
• 要为特定分支、标签或提交运行流水线，您可以使用 触发令牌 进行身份验证，并与 流水线触发器 API 进行交互。 触发令牌不同于 trigger 关键词。

trigger:inputs#

使用 trigger:inputs 来为多项目流水线设置 输入，当下游流水线配置使用 spec:inputs 时。

trigger:inputs 示例:

yaml
trigger:
  - project: 'my-group/my-project'
    inputs:
      website: "My website"

trigger:include#

使用 trigger:include 来声明一个作业是一个"触发作业"，它启动一个子流水线。

此外，还可以使用：

• trigger:include:artifact 来触发一个动态子流水线。
• trigger:include:inputs 来设置 输入，当下游流水线配置使用 spec:inputs 时。

关键字类型: 作业关键字。只能在作业中使用。

支持的值:

• 子流水线配置文件的路径。

trigger:include 示例:

yaml
trigger-child-pipeline:
  trigger:
    include: path/to/child-pipeline.gitlab-ci.yml

相关主题:

• 子流水线配置示例。

trigger:include:inputs#

使用 trigger:include:inputs 来为子流水线设置 输入，当下游流水线配置使用 spec:inputs 时。

trigger:inputs 示例:

yaml
1trigger-job:
2  trigger:
3    include:
4      - local: path/to/child-pipeline.yml
5        inputs:
6          website: "My website"

trigger:project#

使用 trigger:project 来声明一个作业是一个"触发作业"，它启动一个多项目流水线。

默认情况下，多项目流水线会触发默认分支的流水线。使用 trigger:branch 来指定不同的分支。

关键字类型: 作业关键字。只能在作业中使用。

支持的值:

• 下游项目的路径。CI/CD 变量在 极狐GitLab 15.3 及更高版本中 被支持，但不支持 仅限作业的变量。

trigger:project 示例:

yaml
trigger-multi-project-pipeline:
  trigger:
    project: my-group/my-project

不同分支的 trigger:project 示例:

yaml
trigger-multi-project-pipeline:
  trigger:
    project: my-group/my-project
    branch: development

相关主题:

• 多项目流水线配置示例。
• 要为特定分支、标签或提交运行流水线，您还可以使用 触发令牌 来通过 流水线触发 API 进行身份验证。触发令牌与 trigger 关键字不同。

trigger:strategy#

使用 trigger:strategy 来强制 trigger 作业等待下游流水线完成后才被标记为 成功。

此行为与默认的不同，默认情况下，trigger 作业在下游流水线创建后即被标记为 成功。

此设置使您的流水线执行变得线性而不是并行。

trigger:strategy 示例:

yaml
trigger_job:
  trigger:
    include: path/to/child-pipeline.yml
    strategy: depend

在此示例中，后续阶段的作业在触发的流水线成功完成前会等待。

附加细节:

• 下游流水线中的 可选手动作业 不会影响下游流水线或上游触发作业的状态。下游流水线可以在不运行任何可选手动作业的情况下成功完成。
• 下游流水线中的 阻塞手动作业 必须在触发作业标记为成功或失败之前运行。如果由于手动作业导致下游流水线状态为 等待手动操作 (
  )，则触发作业显示为 待处理 (
  )。默认情况下，后续阶段的作业在触发作业完成前不会启动。
• 如果下游流水线有一个失败的作业，但该作业使用了 allow_failure: true，则下游流水线被视为成功，触发作业显示为 成功。

trigger:forward#

使用 trigger:forward 来指定要转发到下游流水线的内容。您可以控制转发到 父子流水线 和 多项目流水线 的内容。

转发的变量默认情况下不会再次转发到嵌套的下游流水线，除非嵌套的下游触发作业也使用 trigger:forward。

支持的值:

• yaml_variables: true（默认）或 false。当为 true 时，触发作业中定义的变量会传递到下游流水线。
• pipeline_variables: true 或 false（默认）。当为 true 时，流水线变量 会传递到下游流水线。

trigger:forward 示例:

手动运行此流水线，使用 CI/CD 变量 MYVAR = my value:

yaml
1variables: # 每个作业的默认变量
2  VAR: value
3
4# 默认行为:
5# - VAR 传递给子流水线
6# - MYVAR 不传递给子流水线
7child1:
8  trigger:
9    include: .child-pipeline.yml
10
11# 转发流水线变量:
12# - VAR 传递给子流水线
13# - MYVAR 传递给子流水线
14child2:
15  trigger:
16    include: .child-pipeline.yml
17    forward:
18      pipeline_variables: true
19
20# 不转发 YAML 变量:
21# - VAR 不传递给子流水线
22# - MYVAR 不传递给子流水线
23child3:
24  trigger:
25    include: .child-pipeline.yml
26    forward:
27      yaml_variables: false

附加细节:

• 使用 trigger:forward 转发到下游流水线的 CI/CD 变量是 流水线变量，具有高优先级。如果下游流水线中定义了同名变量，该变量通常会被转发的变量覆盖。

when#

使用 when 配置作业运行的条件。如果在作业中未定义，默认值为 when: on_success。

关键字类型: 作业关键字。可以作为作业的一部分使用。when: always 和 when: never 也可以在 workflow:rules 中使用。

支持的值:

• on_success（默认）：仅当早期阶段的作业没有失败时运行作业。
• on_failure：仅当早期阶段的至少一个作业失败时运行作业。
• never：无论早期阶段的作业状态如何，都不运行作业。只能在 rules 部分或 workflow: rules 中使用。
• always：无论早期阶段的作业状态如何，都运行作业。
• manual：将作业添加到流水线作为 手动作业。
• delayed：将作业添加到流水线作为 延迟作业。

when 示例:

yaml
1stages:
2  - build
3  - cleanup_build
4  - test
5  - deploy
6  - cleanup
7
8build_job:
9  stage: build
10  script:
11    - make build
12
13cleanup_build_job:
14  stage: cleanup_build
15  script:
16    - cleanup build when failed
17  when: on_failure
18
19test_job:
20  stage: test
21  script:
22    - make test
23
24deploy_job:
25  stage: deploy
26  script:
27    - make deploy
28  when: manual
29  environment: production
30
31cleanup_job:
32  stage: cleanup
33  script:
34    - cleanup after jobs
35  when: always

在此示例中，脚本：

1. 仅在 build_job 失败时执行 cleanup_build_job。
2. 无论成功或失败，总是在流水线的最后一步执行 cleanup_job。
3. 当您在极狐GitLab UI 中手动运行时执行 deploy_job。

附加细节:

• 在评估 on_success 和 on_failure 的作业状态时：
  • 早期阶段中具有 allow_failure: true 的作业被视为成功，即使它们失败。
  • 早期阶段中跳过的作业，例如 未启动的手动作业，被视为成功。
• allow_failure 的默认值为 true，当使用 when: manual 时。默认值在使用 rules:when: manual 时变为 false。

相关主题:

• when 可以与 rules 一起使用，以实现更动态的作业控制。
• when 可以与 workflow 一起使用，以控制流水线何时可以启动。

manual_confirmation#

使用 manual_confirmation 与 when: manual 一起为手动作业定义自定义确认消息。如果没有使用 when: manual 定义的手动作业，则此关键字无效。

关键字类型: 作业关键字。只能在作业中使用。

支持的值:

• 带有确认消息的字符串。

manual_confirmation 示例:

yaml
1delete_job:
2  stage: post-deployment
3  script:
4    - make delete
5  when: manual
6  manual_confirmation: 'Are you sure you want to delete this environment?'

variables#

使用 variables 来定义 CI/CD 变量。

变量可以在 CI/CD 作业中定义，也可以作为顶级（全局）关键字定义默认 CI/CD 变量 用于所有作业。

附加细节:

• 所有 YAML 定义的变量也会设置给任何链接的 Docker 服务容器。
• YAML 定义的变量用于非敏感项目配置。将敏感信息存储在 受保护变量 或 CI/CD 密钥 中。
• 手动流水线变量 和 计划的流水线变量 默认不传递到下游流水线。使用 trigger:forward 将这些变量转发到下游流水线。

相关主题:

• 预定义变量 是 runner 自动创建并在作业中可用的变量。
• 您可以通过变量配置 runner 行为。

作业 variables#

您可以在作业的 script、before_script 或 after_script 部分以及某些 作业关键字 中使用作业变量。查看每个作业关键字的 支持的值 部分，了解是否支持变量。

您不能将作业变量用作 全局关键字 的值，例如 include。

支持的值: 变量名称和值对：

• 名称只能使用数字、字母和下划线 (_)。在某些 shell 中，第一个字符必须是字母。
• 值必须是字符串。

CI/CD 变量 被支持。

作业 variables 示例:

yaml
1review_job:
2  variables:
3    DEPLOY_SITE: "https://dev.example.com/"
4    REVIEW_PATH: "/review"
5  script:
6    - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH

在此示例中：

• review_job 定义了 DEPLOY_SITE 和 REVIEW_PATH 作业变量。两个作业变量都可以在 script 部分中使用。

默认 variables#

在顶级 variables 部分定义的变量作为所有作业的默认变量。

每个默认变量都可以在流水线中的每个作业中使用，除非作业中已经定义了具有相同名称的变量。作业中定义的变量具有 优先级，因此无法在作业中使用具有相同名称的默认变量的值。

与作业变量类似，您不能将默认变量用作其他全局关键字的值，例如 include。

支持的值: 变量名称和值对：

• 名称只能使用数字、字母和下划线 (_)。在某些 shell 中，第一个字符必须是字母。
• 值必须是字符串。

CI/CD 变量 被支持。

variables 示例:

yaml
1variables:
2  DEPLOY_SITE: "https://example.com/"
3
4deploy_job:
5  stage: deploy
6  script:
7    - deploy-script --url $DEPLOY_SITE --path "/"
8  environment: production
9
10deploy_review_job:
11  stage: deploy
12  variables:
13    DEPLOY_SITE: "https://dev.example.com/"
14    REVIEW_PATH: "/review"
15  script:
16    - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH
17  environment: production

在此示例中：

• deploy_job 没有定义变量。默认的 DEPLOY_SITE 变量会被复制到作业中，并且可以在 script 部分中使用。
• deploy_review_job 已经定义了一个 DEPLOY_SITE 变量，因此默认的 DEPLOY_SITE 不会被复制到作业中。作业还定义了一个 REVIEW_PATH 作业变量。两个作业变量都可以在 script 部分中使用。

variables:description#

使用 description 关键字为默认变量定义描述。当在手动运行流水线时预填写变量名称时会显示描述。

关键字类型: 只能与默认 variables 一起使用此关键字，而不能与作业 variables 一起使用。

支持的值:

• 一个字符串。可以使用 Markdown。

variables:description 示例:

yaml
variables:
  DEPLOY_NOTE:
    description: "The deployment note. Explain the reason for this deployment."

附加细节:

• 在没有 value 的情况下使用时，变量存在于未手动触发的流水线中，默认值为空字符串 ('')。

variables:value#

使用 value 关键字定义流水线级别（默认）的变量值。当与 variables: description 一起使用时，变量值在手动运行流水线时预填充。

关键字类型: 只能与默认 variables 一起使用此关键字，而不能与作业 variables 一起使用。

支持的值:

• 一个字符串。

variables:value 示例:

yaml
variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    description: "The deployment target. Change this variable to 'canary' or 'production' if needed."

附加细节:

• 如果不使用 variables: description，行为与 variables 相同。

variables:options#

使用 variables:options 定义一个数组，这些值在手动运行流水线时可以在 UI 中选择。

必须与 variables: value 一起使用，且为 value 定义的字符串：

• 也必须是 options 数组中的字符串之一。
• 是默认选择。

如果没有 description，此关键字无效。

关键字类型: 只能与默认 variables 一起使用此关键字，而不能与作业 variables 一起使用。

支持的值:

• 字符串数组。

variables:options 示例:

yaml
1variables:
2  DEPLOY_ENVIRONMENT:
3    value: "staging"
4    options:
5      - "production"
6      - "staging"
7      - "canary"
8    description: "The deployment target. Set to 'staging' by default."

variables:expand#

使用 expand 关键字配置变量是否可展开。

关键字类型: 可以与默认和作业 variables 一起使用此关键字。

支持的值:

• true（默认）：变量是可展开的。
• false：变量不可展开。

variables:expand 示例:

yaml
1variables:
2  VAR1: value1
3  VAR2: value2 $VAR1
4  VAR3:
5    value: value3 $VAR1
6    expand: false

• VAR2 的结果是 value2 value1。
• VAR3 的结果是 value3 $VAR1。

附加细节:

• expand 关键字只能与默认和作业 variables 关键字一起使用。不能与 rules:variables 或 workflow:rules:variables 一起使用。

弃用的关键词

以下关键词已被弃用。

全局定义的 image、services、cache、before_script、after_script

全局定义 image、services、cache、before_script 和 after_script 已被弃用。仍然可以在顶层使用这些关键词以确保向后兼容，但可能在未来的里程碑中计划移除。

请使用 default 代替。例如：

yaml
1default:
2  image: ruby:3.0
3  services:
4    - docker:dind
5  cache:
6    paths: [vendor/]
7  before_script:
8    - bundle config set path vendor/bundle
9    - bundle install
10  after_script:
11    - rm -rf tmp/

only / except

您可以使用 only 和 except 来控制何时将作业添加到流水线。

• 使用 only 来定义作业运行的时间。
• 使用 except 来定义作业不运行的时间。

only:refs / except:refs

您可以使用 only:refs 和 except:refs 关键词来根据分支名称或流水线类型控制何时将作业添加到流水线。

关键词类型：作业关键词。您只能作为作业的一部分使用它。

支持的值：包括任意数量的数组：

• 分支名称，例如 main 或 my-feature-branch。

• 与分支名称匹配的正则表达式，例如 /^feature-.*/。

• 以下关键词：

  值	描述
  api	对于由 流水线 API 触发的流水线。
  branches	当流水线的 Git 引用为分支时。
  chat	通过使用 极狐GitLab ChatOps 命令创建的流水线。
  external	当您使用极狐GitLab 以外的 CI 服务时。
  external_pull_requests	当在 GitHub 上创建或更新外部拉取请求时（见 外部拉取请求的流水线）。
  merge_requests	当合并请求被创建或更新时创建的流水线。启用合并请求流水线、合并结果流水线和合并列车。
  pipelines	对于 多项目流水线，通过 使用 API 和 CI_JOB_TOKEN 或 trigger 关键词创建。
  pushes	对于由 git push 事件触发的流水线，包括分支和标签。
  schedules	对于 计划的流水线。
  tags	当流水线的 Git 引用为标签时。
  triggers	通过使用 触发令牌 创建的流水线。
  web	通过在极狐GitLab UI 中选择 新建流水线 从项目的 构建 > 流水线 部分创建的流水线。

only:refs 和 except:refs 示例：

yaml
1job1:
2  script: echo
3  only:
4    - main
5    - /^issue-.*$/
6    - merge_requests
7
8job2:
9  script: echo
10  except:
11    - main
12    - /^stable-branch.*$/
13    - schedules

附加细节：

• 计划的流水线在特定分支上运行，因此配置为 only: branches 的作业也会在计划的流水线上运行。添加 except: schedules 来防止配置为 only: branches 的作业在计划的流水线上运行。

• 未与其他任何关键词一起使用的 only 或 except 等同于 only: refs 或 except: refs。例如，以下两个作业配置具有相同的行为：

  yaml
  1job1:
  2  script: echo
  3  only:
  4    - branches
  5
  6job2:
  7  script: echo
  8  only:
  9    refs:
  10      - branches

• 如果作业未使用 only、except 或 rules，则默认情况下设置 only 为 branches 和 tags。

  例如，job1 和 job2 是等效的：

  yaml
  1job1:
  2  script: echo "test"
  3
  4job2:
  5  script: echo "test"
  6  only:
  7    - branches
  8    - tags

only:variables / except:variables

您可以使用 only:variables 或 except:variables 关键词根据 CI/CD 变量 的状态控制何时将作业添加到流水线。

关键词类型：作业关键词。您只能作为作业的一部分使用它。

支持的值：

• CI/CD 变量表达式 的数组。

only:variables 示例：

yaml
1deploy:
2  script: cap staging deploy
3  only:
4    variables:
5      - $RELEASE == "staging"
6      - $STAGING

only:changes / except:changes

only:variables 和 except:variables

使用 only 的 changes 关键词运行作业，或者使用 except 跳过作业，当 Git 推送事件修改文件时。

在具有以下引用的流水线中使用 changes：

• branches
• external_pull_requests
• merge_requests

关键词类型：作业关键词。您只能作为作业的一部分使用它。

支持的值：包括任意数量的数组：

• 文件路径。
• 单个目录的通配符路径，例如 path/to/directory/*。
• 一个目录及其所有子目录的通配符路径，例如 path/to/directory/**/*。
• 所有具有相同扩展名或多个扩展名的文件的通配符 glob 路径，例如 *.md 或 path/to/directory/*.{rb,py,sh}。
• 用双引号括起来的根目录或所有目录中的文件的通配符路径。例如 "*.json" 或 "**/*.json"。

only:changes 示例：

yaml
1docker build:
2  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
3  only:
4    refs:
5      - branches
6    changes:
7      - Dockerfile
8      - docker/scripts/*
9      - dockerfiles/**/*
10      - more_scripts/*.{rb,py,sh}
11      - "**/*.json"

附加细节：

• 如果任何匹配的文件被更改，changes 将解析为 true（OR 操作）。
• Glob 模式使用 Ruby 的 File.fnmatch 进行解释，并带有标志 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB。
• 如果您使用的引用不是 branches、external_pull_requests 或 merge_requests，则 changes 无法确定给定文件是新文件还是旧文件，并且始终返回 true。
• 如果您将 only: changes 与其他引用一起使用，作业将忽略更改并始终运行。
• 如果您将 except: changes 与其他引用一起使用，作业将忽略更改并且永远不会运行。

相关主题：

• 使用 only: changes 时作业或流水线可能意外运行。

only:kubernetes / except:kubernetes

使用 only:kubernetes 或 except:kubernetes 来控制在项目中 Kubernetes 服务处于活动状态时是否将作业添加到流水线。

关键词类型：作业特定。您只能作为作业的一部分使用它。

支持的值：

• kubernetes 策略仅接受 active 关键词。

only:kubernetes 示例：

yaml
deploy:
  only:
    kubernetes: active

在此示例中，deploy 作业仅在项目中 Kubernetes 服务处于活动状态时运行。