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 生成一个 发布 对象。
  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，但由于 问题 213634，此关键字无效。

default 示例：

default:
  image: ruby:3.0
  retry: 2

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: ruby:2.7
  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 将外部 YAML 文件包含在你的 CI/CD 配置中。你可以将一个长的 .gitlab-ci.yml 文件拆分为多个文件以提高可读性，或在多个地方减少相同配置的重复。

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

包含的文件：

• 与 .gitlab-ci.yml 文件中的内容合并。
• 无论 include 关键字的位置如何，始终先进行评估，然后再与 .gitlab-ci.yml 文件的内容合并。

解析所有文件的时间限制为 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 组件的完整地址，格式为 <完全限定域名>/<项目路径>/<组件名称>@<特定版本>。

include:component 示例：

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 示例：

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

你也可以使用更简短的语法定义路径：

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 示例：

include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-subgroup/my-project-2'
    file:
      - '/templates/.builds.yml'
      - '/templates/.tests.yml'

你也可以指定一个 ref：

include:
  - project: 'my-group/my-project'
    ref: main                                      # Git 分支
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: v1.0.0                                    # Git 标签
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b  # Git SHA
    file: '/templates/.gitlab-ci-template.yml'

额外细节：

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

include:remote

使用 include:remote 结合完整URL来从不同位置包含文件。

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

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

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

include:remote 示例：

include:
  - remote: 'https://gitlab.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 示例：

# 文件源自GitLab模板集合
include:
  - template: Auto-DevOps.gitlab-ci.yml

多个 include:template 文件：

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

附加详情：

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

include:inputs

使用 include:inputs 为输入参数设置值，当包含的配置使用 spec:inputs 且被添加到流水线时。

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

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

include:inputs 示例：

include:
  - local: 'custom_configuration.yml'
    inputs:
      website: "我的网站"

在此示例中：

• custom_configuration.yml 中包含的配置会被添加到流水线， 其中包含的配置的 website 输入设置为值 我的网站。

附加详情：

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

相关主题：

• 使用 include 时设置输入值。

include:rules

你可以使用 rules 与 include 配合，有条件地包含其他配置文件。

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

支持值：这些 rules 子键：

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

一些CI/CD变量受支持。

include:rules 示例：

include:
  - local: build_jobs.yml
    rules:
      - if: $INCLUDE_BUILDS == "true"

test-job:
  stage: test
  script: echo "这是一个测试作业"

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

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

相关主题：

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

#### `include:integrity`


    
    
      History 
    
    

Introduced in GitLab 17.9.





使用 `integrity` 与 `include:remote` 配合来指定包含的远程文件的SHA256哈希值。
如果 `integrity` 与实际内容不匹配，远程文件将不被处理，且管道失败。

**关键字类型**：全局关键字。

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

**`include:integrity` 示例**：

```yaml
include:
  - remote: 'https://gitlab.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 示例：

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 示例：

workflow:
  auto_cancel:
    on_new_commit: interruptible

job1:
  interruptible: true
  script: sleep 60

job2:
  interruptible: false  # 未定义时默认值。
  script: sleep 60

在此示例中：

• 当新提交推送到分支时，GitLab创建新管道，job1 和 job2 启动。
• 若在新提交推送前作业未完成，仅 job1 被取消。

#### `workflow:auto_cancel:on_job_failure`


    
    
      History 
    
    

在 GitLab 16.10 中引入（带有一个名为 auto_cancel_pipeline_on_job_failure 的标志）。默认禁用。
在 GitLab 16.11 中普遍可用。移除了功能标志 auto_cancel_pipeline_on_job_failure。





使用 `workflow:auto_cancel:on_job_failure` 来配置在某个作业失败时应取消哪些作业。

**支持的值**：

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

**`workflow:auto_cancel:on_job_failure` 示例**：

```yaml
stages: [stage_a, stage_b]

workflow:
  auto_cancel:
    on_job_failure: all

job1:
  stage: stage_a
  script: sleep 60

job2:
  stage: stage_a
  script:
    - sleep 30
    - exit 1

job3:
  stage: stage_b
  script:
    - sleep 30

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

相关主题：

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

workflow:name

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

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

支持的值：

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

workflow:name 示例：

带有预定义变量的简单流水线名称：

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

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

variables:
  PROJECT1_PIPELINE_NAME: 'Default pipeline name'  # 默认不是必需的

workflow:
  name: '$PROJECT1_PIPELINE_NAME'
  rules:
    - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/'
      variables:
        PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PROJECT1_PIPELINE_NAME: 'MR pipeline: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # 对于默认分支流水线，使用默认名称

附加细节：

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

workflow:rules

工作流（workflow）中的 rules 关键字与作业中定义的 rules 类似，但它控制是否创建整个流水线。

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

支持值：你可以使用一些与作业级 rules 相同的关键字：

• rules: if。
• rules: changes。
• rules: exists。
• when，当与 workflow 一起使用时只能为 always 或 never。
• variables。

workflow:rules 示例：

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

在此示例中，如果提交标题（提交消息的第一行）不以 -draft 结尾，并且流水线用于以下任一情况，则流水线会运行：

• 合并请求
• 默认分支

额外细节：

• 如果你的规则同时匹配分支流水线（除默认分支外）和合并请求流水线，可能会出现重复流水线。
• start_in、allow_failure 和 needs 在 workflow:rules 中不受支持，但不会导致语法错误。尽管它们无效，但不要在 workflow:rules 中使用它们，因为这可能在将来引起语法失败。有关更多详情，请参阅 issue 436473。

相关主题：

• 工作流规则（workflow:rules）的常见 if 子句。
• 使用 rules 运行合并请求流水线。

workflow:rules:variables

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

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

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

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

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

workflow:rules:variables 示例：

variables:
  DEPLOY_VARIABLE: "default-deploy"

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        DEPLOY_VARIABLE: "deploy-production"  # 覆盖全局定义的 DEPLOY_VARIABLE
    - if: $CI_COMMIT_BRANCH =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # 定义新变量。
    - if: $CI_COMMIT_BRANCH                   # 其他情况下运行流水线

job1:
  variables:
    DEPLOY_VARIABLE: "job1-default-deploy"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:                                   # 覆盖作业级别定义的 DEPLOY_VARIABLE
        DEPLOY_VARIABLE: "job1-deploy-production"  # 
    - when: on_success                             # 其他情况下运行作业
  script:
    - echo "以 $DEPLOY_VARIABLE 作为参数运行脚本"
    - echo "如果存在 $IS_A_FEATURE 则运行另一个脚本"

job2:
  script:
    - echo "以 $DEPLOY_VARIABLE 作为参数运行脚本"
    - echo "如果存在 $IS_A_FEATURE 则运行另一个脚本"

当分支是默认分支时：

• 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 示例：

workflow:
  auto_cancel:
    on_new_commit: interruptible
    on_job_failure: all
  rules:
    - if: $CI_COMMIT_REF_PROTECTED == 'true'
      auto_cancel:
        on_new_commit: none
        on_job_failure: none
    - when: always                  # 其他情况始终运行流水线

test-job1:
  script: sleep 10
  interruptible: false

test-job2:
  script: sleep 10
  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 必须在配置文件顶部声明，位于通过 --- 与其余配置分隔的头部部分。

spec:inputs

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

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

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

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

spec:inputs 示例：

spec:
  inputs:
    environment:
    job-stage:
---

scan-website:
  stage: $[[ inputs.job-stage ]]
  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 示例：

spec:
  inputs:
    website:
    user:
      default: 'test-user'
    flags:
      default: ''
title: The pipeline configuration would follow...
---

在此示例中：

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

额外细节：

• 当输入满足以下条件时，管道会因验证错误而失败：
  • 同时使用 default 和 options，但默认值不在选项列表中。
  • 同时使用 default 和 regex，但默认值与正则表达式不匹配。
  • 值与 type 不匹配。

spec:inputs:description

使用 description 为特定输入提供说明。该说明不影响输入的行为，仅用于帮助文件使用者理解输入。

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

支持值：表示说明的字符串。

spec:inputs:description 示例：

spec:
  inputs:
    flags:
      description: 'Sample description of the `flags` input details.'
title: The pipeline configuration would follow...
---

spec:inputs:options

输入可以使用 options 指定允许值的列表。每个输入最多支持 50 个选项。

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

支持值：输入选项数组。

spec:inputs:options 示例：

spec:
  inputs:
    environment:
      options:
        - development
        - staging
        - production
title: The pipeline configuration would follow...
---

在此示例中：

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

额外细节：

• 当满足以下条件时，管道会因验证错误而失败：
  • 同时使用 options 和 default，但默认值不在选项列表中。
  • 任何输入选项与 type 不匹配（使用 options 时不能是 boolean）。

spec:inputs:regex

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

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

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

spec:inputs:regex 示例：

spec:
  inputs:
    version:
      regex: ^v\d\.\d+(\.\d+)?$
title: The pipeline configuration would follow...
---

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

额外细节：

• inputs:regex 只能与 type 为 string 一起使用，不能是 number 或 boolean。
• 不要用 / 包裹正则表达式（例如，使用 regex.* 而非 /regex.*/）。
• inputs:regex 使用 RE2 解析正则表达式。

spec:inputs:type

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

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

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

• array：接受输入数组。
• string：接受字符串输入（未定义时默认）。
• number：仅接受数字输入。
• boolean：仅接受 true 或 false 输入。

spec:inputs:type 示例：

spec:
  inputs:
    job_name:
    website:
      type: string
    port:
      type: number
    available:
      type: boolean
    array_input:
      type: array
title: The pipeline configuration would follow...
---

作业关键词

以下主题解释如何使用关键词配置CI/CD管道。

after_script

使用after_script定义一个命令数组，这些命令在作业的before_script和script部分完成后最后运行。after_script命令还会在以下情况运行：

• 当before_script或script部分仍在运行时，作业被取消。
• 作业因script_failure类型的失败而失败，但不是其他失败类型。

关键词类型：作业关键词。你只能在作业中使用它，或在default部分中使用。

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

• 单行命令。
• 长命令跨多行拆分。
• YAML锚点。

CI/CD变量受支持。

after_script示例:

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

额外细节:

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

• 当前工作目录会重置为默认值（根据定义运行器如何处理Git请求的变量）。
• 无法访问before_script或script中定义的命令所做的更改，包括：
  • script脚本中导出的命令别名和变量。
  • 工作树外的更改（取决于运行器执行器），例如由before_script或script脚本安装的软件。
• 有单独的超时时间。对于GitLab Runner 16.4及更高版本，默认为5分钟，可通过RUNNER_AFTER_SCRIPT_TIMEOUT变量进行配置。在GitLab 16.3及更早版本中，超时时间是硬编码为5分钟的。
• 不影响作业的退出码。如果script部分成功，而after_script超时或失败，作业将以代码0（Job Succeeded）退出。
• 使用CI/CD作业令牌与after_script存在已知问题。你可以在after_script命令中使用作业令牌进行身份验证，但如果作业被取消，该令牌会立即失效。有关更多详情，请参阅问题。

对于超时的作业：

• 默认情况下，after_script命令不会执行。
• 你可以配置超时值，通过设置不超过作业超时的适当RUNNER_SCRIPT_TIMEOUT和RUNNER_AFTER_SCRIPT_TIMEOUT值来确保after_script运行。

相关主题:

• 将after_script与default一起使用，以定义应在所有作业后运行的默认命令数组。
• 你可以配置作业以跳过after_script命令（如果作业被取消）。
• 你可以忽略非零退出码。
• 在after_script中使用颜色代码，使作业日志更容易查看。
• 创建自定义可折叠部分，简化作业日志输出。
• 你可以忽略after_script中的错误。

allow_failure

使用 allow_failure 来确定当作业失败时，管道是否应继续运行。

• 若要让管道继续运行后续作业，请使用 allow_failure: true。
• 若要停止管道运行后续作业，请使用 allow_failure: false。

当允许作业失败（allow_failure: true）时，会显示橙色警告（ ），表示该作业失败。不过，管道仍算成功，相关提交会被标记为通过且无警告。

以下情况也会显示此警告：

• 该阶段的所有其他作业均成功。
• 管道中的所有其他作业均成功。

allow_failure 的默认值为：

• 对于手动作业，为 true。
• 对于在rules中使用 when: manual 的作业，为 false。
• 其他所有情况均为 false。

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

支持的值：

• true 或 false。

allow_failure 示例：

job1:
  stage: test
  script:
    - execute_script_1

job2:
  stage: test
  script:
    - execute_script_2
  allow_failure: true

job3:
  stage: deploy
  script:
    - deploy_to_staging
  environment: staging

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

• 如果 job1 失败，deploy 阶段的作业不会启动。
• 如果 job2 失败，deploy 阶段的作业仍可启动。

附加详情：

• 你可以将 allow_failure 用作 rules 的子键。
• 若设置 allow_failure: true，该作业始终被视为成功；若此作业失败，使用 when: on_failure 的后续作业不会启动。
• 你可以使用 allow_failure: false 与手动作业结合，创建一个阻塞型手动作业。被阻塞的管道在手动作业启动并成功完成前，不会运行后续阶段的任何作业。

allow_failure:exit_codes

使用 allow_failure:exit_codes 来控制何时允许作业失败。对于列出的任意退出码，作业视为 allow_failure: true；对于其他任意退出码，则为 allow_failure: false。

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

支持的值：

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

allow_failure 示例：

test_job_1:
  script:
    - echo "Run a script that results in exit code 1. This job fails."
    - exit 1
  allow_failure:
    exit_codes: 137

test_job_2:
  script:
    - echo "Run a script that results in exit code 137. This job is allowed to fail."
    - exit 137
  allow_failure:
    exit_codes:
      - 137
      - 255

artifacts

使用 artifacts 指定要作为作业制品保存的文件。作业制品是一组文件和目录，会在作业成功、失败或始终时附加到作业中。

制品在作业完成后发送至 GitLab。如果大小小于最大制品大小，则可在 GitLab UI 中下载。

默认情况下，后续阶段的作业会自动下载由较早阶段作业创建的所有制品。你可以通过 dependencies 控制作业中的制品下载行为。

使用 needs 关键字时，作业只能从 needs 配置中定义的作业下载制品。

默认情况下，仅对成功的作业收集制品，且制品会在缓存后恢复。

阅读更多关于制品的内容。

artifacts:paths

路径相对于项目目录（$CI_PROJECT_DIR），不能直接链接到其外部。

关键词类型：作业关键字。你只能在作业中或 default 部分 中使用它。

支持的值：

• 项目目录下的文件路径数组。
• 你可以使用支持 glob 模式和 doublestar.Glob 模式的通配符。
• 针对 GitLab Pages 作业：
  • 在 GitLab 17.10 及更高版本 中，pages.publish 路径会自动附加到 artifacts:paths，因此你无需再次指定。
  • 在 GitLab 17.10 及更高版本 中，当未指定 pages.publish 路径时，public 目录会自动附加到 artifacts:paths。

CI/CD 变量 受支持。

artifacts:paths 示例：

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

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

额外细节：

• 如果未与 artifacts:name 一起使用，则工件文件名为 artifacts，下载时会变为 artifacts.zip。

相关主题：

• 要限制特定作业从哪些作业获取工件，请参阅 dependencies。
• 创建作业工件。

artifacts:exclude

使用 artifacts:exclude 防止文件被添加到工件存档中。

关键词类型：作业关键字。你只能在作业中或 default 部分 中使用它。

支持的值：

• 项目目录下的文件路径数组。
• 你可以使用支持 glob 或 doublestar.PathMatch 模式的通配符。

artifacts:exclude 示例：

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

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

额外细节：

• artifacts:exclude 路径不会递归搜索。
• 由 artifacts:untracked 匹配的文件也可以用 artifacts:exclude 排除。

相关主题：

• 排除作业工件中的文件。

artifacts:expire_in

使用 expire_in 指定 作业工件 在过期并被删除前存储的时间。expire_in 设置不影响：

• 最新作业的工件，除非在 项目级别 或 实例范围 禁用了保留最新作业工件。

过期后，工件默认每小时（通过 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 示例：

job:
  artifacts:
    expire_in: 1 week

额外细节：

• 过期时间从工件上传并存储到 GitLab 时开始计算。如果未定义过期时间，则默认为 实例范围的设置。
• 要覆盖过期日期并防止工件被自动删除：
  • 在作业页面上选择 Keep。
  • 将 expire_in 的值设为 never。
• 如果过期时间过短，长流水线后续阶段的作业可能会尝试从早期作业中获取已过期的工件。如果工件已过期，尝试获取它们的作业会因 无法检索所需工件 错误 而失败。延长过期时间，或在后续作业中使用 dependencies，以确保它们不会尝试获取已过期的工件。
• artifacts:expire_in 不影响 GitLab Pages 部署。要配置 Pages 部署的过期时间，请使用 pages.expire_in。

artifacts:expose_as

使用 artifacts:expose_as 关键字可在合并请求界面中展示作业工件。

关键字类型：作业关键字。你只能在作业内或 default 部分 中使用它。

支持值：

• 在合并请求界面中显示的工件下载链接的名称。必须与 artifacts:paths 配合使用。

artifacts:expose_as 示例：

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

附加细节：

• 工件会被保存，但如果 artifacts:paths 的值满足以下条件，则不会在界面中显示：
  • 使用了 CI/CD 变量。
  • 定义了目录，但未以 / 结尾（例如，directory/ 可配合 artifacts:expose_as 使用，但 directory 不行）。
  • 以 ./ 开头（例如，file 可配合 artifacts:expose_as 使用，但 ./file 不行）。
• 每个合并请求最多可暴露 10 个作业工件。
• 不支持 glob 模式。
• 如果指定了目录且目录内有多个文件，链接会指向作业工件浏览器。
• 若启用了 GitLab Pages，当工件是单个文件且扩展名为以下之一时，GitLab 会自动渲染：
  • .html 或 .htm
  • .txt
  • .json
  • .xml
  • .log

相关主题：

• 在合并请求界面中展示作业工件。

artifacts:name

使用 artifacts:name 关键字定义创建的工件存档的名称。你可以为每个存档指定唯一名称。

若未定义，默认名称为 artifacts，下载时会变成 artifacts.zip。

关键字类型：作业关键字。你只能在作业内或 default 部分 中使用它。

支持值：

• 工件存档的名称。支持 CI/CD 变量（详见何处可以使用变量）。必须与 artifacts:paths 配合使用。

artifacts:name 示例：
要创建一个名为当前作业的存档：

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

相关主题：

• 使用 CI/CD 变量定义工件配置

artifacts:public

使用 artifacts:public 确定作业工件是否应公开可用。

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

若要拒绝公共流水线中这些用户对工件的读取权限，可将 artifacts:public 设为 false：

关键字类型：作业关键字。你只能在作业内或 default 部分 中使用它。

支持值：

• true（未定义时默认）或 false。

artifacts:public 示例：

job:
  artifacts:
    public: false

artifacts:access

使用 artifacts:access 确定谁可以从 GitLab UI 或 API 访问作业工件。此选项不会阻止你将工件转发给下游流水线。

你不能在同一作业中同时使用 artifacts:public 和 artifacts:access。

关键字类型：作业关键字。你只能在作业内使用它。

支持值：

• all（默认）：公共流水线中的作业工件可供任何人下载，包括匿名用户、访客和报告者。
• developer：仅具有开发者角色或更高权限的用户可下载该作业的工件。
• none：无人可下载该作业的工件。

artifacts:access 示例：

job:
  artifacts:
    access: 'developer'

附加细节：

• artifacts:access 也会影响所有 artifacts:reports，因此你也可以限制对报告工件的访问。

artifacts:reports

使用 artifacts:reports 收集由包含模板生成的制品。

关键词类型：作业关键字。你只能在作业中或 default 部分 中使用它。

支持值：

• 查看 artifacts 报告类型 列表。

artifacts:reports 示例：

rspec:
  stage: test
  script:
    - bundle install
    - rspec --format RspecJunitFormatter --out rspec.xml
  artifacts:
    reports:
      junit: rspec.xml

附加详情：

• 在父管道中使用 子管道的制品 组合报告不受支持。跟踪添加支持的进展可在 此问题 中查看。
• 要能够浏览和下载报告输出文件，请包含 artifacts:paths 关键字。这会两次上传并存储制品。
• 无论作业结果（成功或失败），为 artifacts: reports 创建的制品总是会上传。你可以使用 artifacts:expire_in 设置制品的过期日期。

artifacts:untracked

使用 artifacts:untracked 添加所有 Git 未跟踪文件作为制品（以及 artifacts:paths 中定义的路径）。artifacts:untracked 忽略仓库 .gitignore 中的配置，因此 .gitignore 中匹配的制品会被包含。

关键词类型：作业关键字。你只能在作业中或 default 部分 中使用它。

支持值：

• true 或 false（未定义时默认）。

artifacts:untracked 示例：

保存所有 Git 未跟踪文件：

job:
  artifacts:
    untracked: true

相关主题：

• 将未跟踪文件添加到制品。

artifacts:when

使用 artifacts:when 在作业失败或即使失败时上传制品。

关键词类型：作业关键字。你只能在作业中或 default 部分 中使用它。

支持值：

• on_success（默认）：仅在作业成功时上传制品。
• on_failure：仅在作业失败时上传制品。
• always：始终上传制品（除作业超时外）。例如，当 上传制品 需要排查失败的测试时。

artifacts:when 示例：

job:
  artifacts:
    when: on_failure

附加详情：

• 为 artifacts:reports 创建的制品总是会上传，无论作业结果（成功或失败）。artifacts:when 不会改变此行为。

before_script

使用 before_script 定义一组命令，这些命令应在每个作业的 script 命令之前运行，但在恢复 制品 之后。

关键词类型：作业关键字。你只能在作业中或 default 部分 中使用它。

支持值：一个数组，包括：

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

CI/CD 变量 受支持。

before_script 示例：

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

附加详情：

• 你在 before_script 中指定的脚本将与主 script 中指定的任何脚本连接在一起。组合后的脚本将在单个 shell 中一起执行。
• 在顶级使用 before_script 但不在 default 部分中，已弃用。

相关主题：

• 使用 before_script 与 default 为所有作业的 script 命令定义默认命令数组。
• 你可以 忽略非零退出码。
• 对 before_script 使用颜色代码 使作业日志更易审阅。
• 创建自定义可折叠部分 简化作业日志输出。

cache

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

缓存具有以下特点：

• 在流水线和作业之间共享。
• 默认情况下，不会在 受保护的分支 和非受保护分支之间共享。
• 在 制品 之前恢复。
• 最多限制为四个不同的缓存（使用多个缓存）。

你可以 为特定作业禁用缓存，例如用于覆盖：

• 使用 default 定义的默认缓存。
• 通过 include 添加的作业配置。

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

cache:paths

使用 cache:paths 关键字来选择要缓存的文件或目录。

关键字类型：作业关键字。你只能在作业中使用它，或者在 default 部分 中使用。

支持值：

• 相对于项目目录（$CI_PROJECT_DIR）的路径数组。你可以使用基于 glob 和 doublestar.Glob 模式的通配符。
• 支持 CI/CD 变量。

cache:paths 示例：

缓存 binaries 目录中以 .apk 结尾的所有文件以及 .config 文件：

rspec:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache
    paths:
      - binaries/*.apk
      - .config

额外细节：

• cache:paths 关键字会包含文件，即使它们未被跟踪或在你的 .gitignore 文件中。

相关主题：

• 请参阅 常见的 cache 用法 以获取更多 cache:paths 示例。

cache:key

使用 cache:key 关键字为每个缓存提供一个唯一的标识键。所有使用相同缓存键的作业都会使用相同的缓存，包括在不同流水线中。

如果未设置，默认键为 default。所有带有 cache 关键字但没有 cache:key 的作业都会共享 default 缓存。

必须与 cache:paths 一起使用，否则不会缓存任何内容。

关键字类型：作业关键字。你只能在作业中使用它，或者在 default 部分 中使用。

支持值：

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

cache:key 示例：

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache-$CI_COMMIT_REF_SLUG
    paths:
      - binaries/

额外细节：

• 如果你使用 Windows Batch 运行 shell 脚本，你必须将 $ 替换为 %。例如：key: %CI_COMMIT_REF_SLUG%
• cache:key 值不能包含：
  • / 字符，或等效的 URI 编码 %2F。
  • 仅 . 字符（任意数量），或等效的 URI 编码 %2E。
• 缓存在作业之间共享，因此如果你为不同作业使用不同的路径，你也应该设置不同的 cache:key。否则缓存内容可能会被覆盖。

相关主题：

• 你可以指定一个 回退缓存键，当指定的 cache:key 未找到时使用。
• 你可以在单个作业中 使用多个缓存键。
• 请参阅 常见的 cache 用法 以获取更多 cache:key 示例。

cache:key:files

使用 cache:key:files 关键词来生成新的键，当匹配定义的路径或模式的文件发生变化时。cache:key:files 让你可以重用一些缓存，并减少重建次数，从而加快后续流水线运行的效率。

关键词类型：作业关键词。你只能在作业中使用它，或者在默认部分中使用。

支持值：

• 最多包含两个文件路径或模式的数组。

CI/CD 变量不被支持。

cache:key:files 示例：

cache-job:
  script:
    - echo "此作业使用缓存。"
  cache:
    key:
      files:
        - Gemfile.lock
        - package.json
    paths:
      - vendor/ruby
      - node_modules

此示例为 Ruby 和 Node.js 依赖项创建缓存。该缓存与当前版本的 Gemfile.lock 和 package.json 文件绑定。当其中一个文件更改时，会计算新的缓存键并创建新缓存。任何未来使用相同 Gemfile.lock 和 package.json 且配置了 cache:key:files 的作业运行都会使用新缓存，而不是重新构建依赖项。

附加详情：

• 缓存 key 是基于每个列出文件的最近提交计算的 SHA 值。 如果没有任何提交修改这些文件，回退键为 default。
• 可以使用通配符模式，如 **/package.json。问题 存在以增加缓存键允许的路径或模式数量。

cache:key:prefix

使用 cache:key:prefix 将前缀与为 cache:key:files 计算的 SHA 结合起来。

关键词类型：作业关键词。你只能在作业中使用它，或者在默认部分中使用。

支持值：

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

cache:key:prefix 示例：

rspec:
  script:
    - echo "此 rspec 作业使用缓存。"
  cache:
    key:
      files:
        - Gemfile.lock
      prefix: $CI_JOB_NAME
    paths:
      - vendor/ruby

例如，添加 $CI_JOB_NAME 作为 prefix 会使键看起来像 rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5。如果某个分支修改了 Gemfile.lock，该分支会有一个新的 SHA 校验和用于 cache:key:files。会生成新的缓存键，并为该键创建新缓存。如果未找到 Gemfile.lock，前缀会被添加到 default 上，因此示例中的键会是 rspec-default。

附加详情：

• 如果 cache:key:files 中的任何文件在任何提交中都未被修改，前缀会被添加到 default 键上。

cache:untracked

使用 untracked: true 来缓存 Git 仓库中所有未跟踪的文件。未跟踪文件包括：

• 因 .gitignore 配置 而被忽略的文件。
• 已创建但未通过 git add 添加到检出中的文件。

缓存未跟踪文件可能会导致意外的大缓存，如果作业下载：

• 通常未跟踪的依赖项，如 gem 或 node 模块。
• 来自不同作业的工件。从工件中提取的文件默认是未跟踪的。

关键词类型：作业关键词。你只能在作业中使用它，或者在默认部分中使用。

支持值：

• true 或 false（默认）。

cache:untracked 示例：

rspec:
  script: test
  cache:
    untracked: true

附加详情：

• 你可以将 cache:untracked 与 cache:paths 组合，以缓存所有未跟踪文件以及配置路径中的文件。 使用 cache:paths 缓存任何特定文件，包括已跟踪文件或工作目录外的文件， 并使用 cache: untracked 同时缓存所有未跟踪文件。例如：

  rspec:
    script: test
    cache:
      untracked: true
      paths:
        - binaries/

  在此示例中，作业缓存仓库中所有未跟踪文件，以及 binaries/ 目录下的所有文件。 如果 binaries/ 中存在未跟踪文件，它们会被这两个关键词覆盖。

cache:unprotect

使用 cache:unprotect 设置缓存可在受保护和未受保护的分支之间共享。

关键词类型：作业关键词。你只能在作业中使用它，或者在默认部分中使用。

支持值：

• true 或 false（默认）。

cache:unprotect 示例：

rspec:
  script: test
  cache:
    unprotect: true

cache:when

使用 cache:when 定义何时保存缓存，依据作业状态而定。

必须与 cache: paths 一起使用，否则不会缓存任何内容。

关键字类型：作业关键字。你只能在作业中使用它，或在 default 部分 中使用。

支持值：

• on_success（默认）：仅在作业成功时保存缓存。
• on_failure：仅在作业失败时保存缓存。
• always：始终保存缓存。

cache:when 示例：

rspec:
  script: rspec
  cache:
    paths:
      - rspec/
    when: 'always'

此示例无论作业是否失败或成功都会存储缓存。

cache:policy

要更改缓存的下载和上传行为，请使用 cache:policy 关键字。
默认情况下，作业开始时会下载缓存，作业结束时会将更改上传到缓存。这种缓存风格是 pull-push 策略（默认）。

若要让作业仅在下一次作业开始时下载缓存，但在作业完成时从不上传更改，请使用 cache:policy:pull。

若要让作业仅在作业完成时上传缓存，但在作业开始时不下载缓存，请使用 cache:policy:push。

当你有大量并行执行的作业使用相同缓存时，请使用 pull 策略。此策略可加快作业执行速度并减少缓存服务器负载。你可以使用带有 push 策略的作业来构建缓存。

必须与 cache: paths 一起使用，否则不会缓存任何内容。

关键字类型：作业关键字。你只能在作业中使用它，或在 default 部分 中使用。

支持值：

• pull
• push
• pull-push（默认）
• CI/CD 变量

cache:policy 示例：

prepare-dependencies-job:
  stage: build
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: push
  script:
    - echo "此作业仅下载依赖项并构建缓存。"
    - echo "下载依赖项..."

faster-test-job:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - echo "此作业脚本使用缓存，但不更新它。"
    - echo "运行测试..."

相关主题：

• 你可以 使用变量控制作业的缓存策略。

cache:fallback_keys

使用 cache:fallback_keys 指定一组键，用于在未找到 cache:key 对应的缓存时尝试从中恢复缓存。缓存按 fallback_keys 部分中指定的顺序检索。

关键字类型：作业关键字。你只能在作业中使用它，或在 default 部分 中使用。

支持值：

• 一组缓存键数组

cache:fallback_keys 示例：

rspec:
  script: rspec
  cache:
    key: gems-$CI_COMMIT_REF_SLUG
    paths:
      - rspec/
    fallback_keys:
      - gems
    when: 'always'

coverage

使用 coverage 和自定义正则表达式来配置如何从作业输出中提取代码覆盖率。如果作业输出中至少有一行匹配该正则表达式，则会在 UI 中显示覆盖率。

要从匹配结果中提取代码覆盖率值，GitLab 使用更小的正则表达式：\d+(?:\.\d+)?。

支持值：

• 一个 RE2 正则表达式。必须以 / 开头和结尾。必须匹配覆盖率数字。也可以匹配周围的文本，因此无需使用正则表达式字符组来捕获确切的数字。由于它使用 RE2 语法，所有组都必须是非捕获的。

coverage 示例：

job1:
  script: rspec
  coverage: '/Code coverage: \d+(?:\.\d+)?/'

在此示例中：

1. GitLab 检查作业日志以查找与正则表达式的匹配。像 Code coverage: 67.89% of lines covered 这样的行会匹配。
2. GitLab 然后检查匹配的片段以找到与正则表达式 \d+(?:\.\d+)? 的匹配。示例正则表达式可以匹配 67.89 的代码覆盖率。

附加详情：

• 你可以在 代码覆盖率 中找到正则表达式示例。
• 如果作业输出中有多个匹配行，则使用最后一行（反向搜索的第一个结果）。
• 如果单行中有多个匹配项，则会搜索最后一个匹配项以获取覆盖率数字。
• 如果匹配片段中发现多个覆盖率数字，则使用第一个数字。
• 会移除前导零。
• 子流水线 的覆盖率输出不会被记录或显示。有关更多详情，请查看 相关问题。

dast_configuration

使用 dast_configuration 关键字来指定要在 CI/CD 配置中使用的站点配置文件和扫描器配置文件。这两个配置文件必须先在项目中创建好。作业的阶段必须是 dast。

关键字类型：作业关键字。你只能将其用作作业的一部分。

支持值：各一个 site_profile 和 scanner_profile。

• 使用 site_profile 指定作业中要使用的站点配置文件。
• 使用 scanner_profile 指定作业中要使用的扫描器配置文件。

dast_configuration 示例：

stages:
  - build
  - dast

include:
  - template: DAST.gitlab-ci.yml

dast:
  dast_configuration:
    site_profile: "Example Co"
    scanner_profile: "Quick Passive Test"

在此示例中，dast 作业扩展了通过 include 关键字添加的 dast 配置，以选择特定的站点配置文件和扫描器配置文件。

额外细节：

• 包含在站点配置文件或扫描器配置文件中的设置优先于 DAST 模板中包含的设置。

相关主题：

• 站点配置文件。
• 扫描器配置文件。

dependencies

使用 dependencies 关键字定义要从哪些特定作业获取工件的列表。指定的作业都必须处于更早的阶段。你也可以将作业设置为完全不下载任何工件。

当作业中未定义 dependencies 时，所有较早阶段的作业都被视为依赖项，该作业会从这些作业获取所有工件。

若要从同一阶段的作业获取工件，你必须使用 needs:artifacts。你不应在同一个作业中同时使用 dependencies 和 needs。

关键字类型：作业关键字。你只能将其用作作业的一部分。

支持值：

• 要从中获取工件的作业名称。
• 一个空数组（[]），用于将该作业配置为不下载任何工件。

dependencies 示例：

build osx:
  stage: build
  script: make build:osx
  artifacts:
    paths:
      - binaries/

build linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
      - binaries/

test osx:
  stage: test
  script: make test:osx
  dependencies:
    - build osx

test linux:
  stage: test
  script: make test:linux
  dependencies:
    - build linux

deploy:
  stage: deploy
  script: make deploy
  environment: production

在此示例中，两个作业有工件：build osx 和 build linux。当执行 test osx 时，会下载并提取 build osx 的工件到构建上下文中。test linux 和 build linux 的工件也是如此。

由于阶段的优先级，deploy 作业会从所有之前的作业下载工件。

额外细节：

• 作业状态无关紧要。如果作业失败或手动作业未被触发，不会发生错误。
• 如果依赖作业的工件已过期或被删除，则作业失败。

environment

使用 environment 定义作业部署到的环境。

关键字类型：作业关键字。你只能将其用作作业的一部分。

支持值：作业部署到的环境的名称，格式如下：

• 纯文本，包括字母、数字、空格以及这些字符：-、_、/、$、{、}。
• CI/CD 变量，包括预定义、项目、组、实例或在 .gitlab-ci.yml 文件中定义的变量。不能使用在 script 部分中定义的变量。

environment 示例：

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment: production

额外细节：

• 如果指定了 environment 且不存在同名的环境，则会创建一个环境。

environment:name

设置环境的名称。

常见环境名称如 qa、staging 和 production，但你也可以使用任意名称。

关键字类型：作业关键字。你只能将其用作作业的一部分。

支持值：作业部署到的环境的名称，格式如下：

• 纯文本，包括字母、数字、空格以及这些字符：-、_、/、$、{、}。
• CI/CD 变量，包括预定义、项目、组、实例或在 .gitlab-ci.yml 文件中定义的变量。不能使用在 script 部分中定义的变量。

environment:name 示例：

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production

environment:url

为环境设置一个URL。

关键字类型：作业关键字。你只能将其用作作业的一部分。

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

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

environment:url 示例：

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production
    url: https://prod.example.com

附加细节：

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

environment:on_stop

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

关键字类型：作业关键字。你只能将其用作作业的一部分。

附加细节：

• 有关更多详情和示例，请参阅environment:action。

environment:action

使用action关键字指定作业如何与环境交互。

关键字类型：作业关键字。你只能将其用作作业的一部分。

支持的值：以下关键字之一：

environment:action 示例：

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

environment:auto_stop_in

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

关键字类型：作业关键字。你只能将其用作作业的一部分。

支持的值：用自然语言书写的时间段。例如，以下都是等效的：

• 168 hours
• 7 days
• one week
• never

CI/CD 变量受支持。

environment:auto_stop_in 示例：

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

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

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

相关主题：

• 环境自动停止文档。

environment:kubernetes

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

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

支持值：

• agent：一个字符串，指定 GitLab Kubernetes代理。格式为 path/to/agent/project:agent-name。如果代理连接到运行管道的项目，请使用 $CI_PROJECT_PATH:agent-name。
• namespace：一个字符串，表示部署环境的Kubernetes命名空间。必须与 agent 关键字一起设置。
• flux_resource_path：一个字符串，表示Flux资源的完整路径（例如HelmRelease）。必须与 agent 和 namespace 关键字一起设置。

environment:kubernetes 示例：

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      agent: path/to/agent/project:agent-name
      namespace: my-namespace
      flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

此配置：

• 设置 deploy 作业以部署到 production 环境
• 将名为 agent-name 的 代理 与环境关联
• 为具有命名空间 my-namespace 且 flux_resource_path 设为 helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource 的环境配置 Kubernetes仪表板

附加细节：

• 要使用仪表板，你必须 安装GitLab Kubernetes代理，并为环境的项目或其父组 配置 user_access。
• 运行作业的用户必须有权访问集群代理。否则，仪表板会忽略 agent、namespace 和 flux_resource_path 属性。
• 如果你想仅设置 agent，则不必设置 namespace，也不能设置 flux_resource_path。但是，此配置会在Kubernetes仪表板中列出集群中的所有命名空间。

environment:deployment_tier

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

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

支持值：以下之一：

• production
• staging
• testing
• development
• other

environment:deployment_tier 示例：

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

此配置：

• 创建一个名为 customer-portal 且部署层级为 production 的环境

附加细节：

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

相关主题：

• 环境的部署层级。

动态环境

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

例如：

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    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访问。

常见用例是为分支创建动态环境并将其用作预览应用。你可以查看使用预览应用的示例：https://gitlab.com/gitlab-examples/review-apps-nginx/。

extends

使用 extends 来复用配置片段。它是 YAML 锚点 的替代方案，并且更灵活且可读性更强。

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

支持的值：

• 另一个管道中的作业名称。
• 一个列表（数组），包含其他管道中的作业名称。

extends 示例：

.tests:
  stage: test
  image: ruby:3.0

rspec:
  extends: .tests
  script: rake rspec

rubocop:
  extends: .tests
  script: bundle exec rubocop

在这个示例中，rspec 作业使用了 .tests 模板作业的配置。创建管道时，GitLab 会：

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

组合后的配置等效于这些作业：

rspec:
  stage: test
  image: ruby:3.0
  script: rake rspec

rubocop:
  stage: test
  image: ruby:3.0
  script: bundle exec rubocop

额外细节：

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

相关主题：

• 通过使用 extends 复用配置片段。
• 结合使用 extends 和 include 来复用配置文件 中的配置。

hooks

使用 hooks 来指定要在运行器上执行的命令列表，以在作业执行的某些阶段执行，例如在获取 Git 仓库之前。

关键词类型：作业关键字。你只能在作业或 default 部分 中使用它。

支持的值：

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

hooks:pre_get_sources_script

使用 hooks:pre_get_sources_script 来指定要在运行器上执行的命令列表，以在克隆 Git 仓库及其子模块之前执行。例如可以用于：

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

支持的值：一个数组，包括：

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

CI/CD 变量 受支持。

hooks:pre_get_sources_script 示例：

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

相关主题：

• GitLab 运行器配置

identity

此功能处于 beta 阶段。

使用 identity 通过身份联合验证第三方服务。

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

支持值：标识符。支持的服务商：

• google_cloud：Google 云端平台。必须配置 Google Cloud IAM 集成。

identity 示例：

job_with_workload_identity:
  identity: google_cloud
  script:
    - gcloud compute instances list

相关主题：

• 工作负载身份联合（Workload Identity Federation）。
• Google Cloud IAM 集成。

id_tokens

使用 id_tokens 创建 JSON Web Tokens (JWT)，以通过第三方服务进行身份验证。通过这种方式创建的所有 JWT 都支持 OIDC 身份验证。必需的 aud 子关键字用于配置 JWT 的 aud 声明。

支持值：

• 包含其 aud 声明的令牌名称。aud 支持：
  • 单个字符串。
  • 字符串数组。
  • CI/CD 变量。

id_tokens 示例：

job_with_id_tokens:
  id_tokens:
    ID_TOKEN_1:
      aud: https://vault.example.com
    ID_TOKEN_2:
      aud:
        - https://gcp.com
        - https://aws.com
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - command_to_authenticate_with_vault $ID_TOKEN_1
    - command_to_authenticate_with_aws $ID_TOKEN_2
    - command_to_authenticate_with_gcp $ID_TOKEN_2

相关主题：

• ID 令牌身份验证。
• 连接云服务。
• 无密钥签名与 Sigstore。

image

使用 image 指定作业运行的 Docker 镜像。

关键字类型：作业关键字。你只能在作业中或 default 部分 中使用它。

支持值：镜像名称，如果需要包含注册表路径，可采用以下格式之一：

• <image-name>（等同于使用带有 latest 标签的 <image-name>）
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD 变量 受支持。

image 示例：

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: registry.example.com/my-group/my-project/ruby:2.7
  script: bundle exec rspec

在此示例中，ruby:3.0 镜像是管道中所有作业的默认镜像。rspec 2.7 作业未使用默认设置，因为它用自己的 image 节覆盖了默认值。

相关主题：

• 在 Docker 容器中运行 CI/CD 作业。

image:name

作业运行的 Docker 镜像名称。类似于单独使用的 image。

关键字类型：作业关键字。你只能在作业中或 default 部分 中使用它。

支持值：镜像名称，如果需要包含注册表路径，可采用以下格式之一：

• <image-name>（等同于使用带有 latest 标签的 <image-name>）
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD 变量 受支持。

image:name 示例：

test-job:
  image:
    name: "registry.example.com/my/image:latest"
  script: echo "Hello world"

相关主题：

• 在 Docker 容器中运行 CI/CD 作业。

image:entrypoint

作为容器入口点执行的命令或脚本。

当创建 Docker 容器时，entrypoint 会转换为 Docker 的 --entrypoint 选项。 其语法类似于 Dockerfile ENTRYPOINT 指令，其中每个 shell 标记在数组中是一个单独的字符串。

关键字类型：作业关键字。你只能在作业中使用它，或在 default 部分 中使用。

支持的值：

• 一个字符串。

image:entrypoint 示例：

test-job:
  image:
    name: super/sql:experimental
    entrypoint: [""]
  script: echo "Hello world"

相关主题：

• 覆盖镜像的入口点。

image:docker

使用 image:docker 向 Docker 执行器 和 Kubernetes 执行器 传递选项。此关键字不适用于其他执行器类型。

关键字类型：作业关键字。你只能在作业中使用它，或在 default 部分 中使用。

支持的值：

一个用于 Docker 执行器的选项哈希，可以包含：

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

image:docker 示例：

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    docker:
      platform: arm64/v8
      user: dave

附加细节：

• image:docker:platform 对应于 docker pull --platform 选项。
• image:docker:user 对应于 docker run --user 选项。

image:kubernetes

使用 image:kubernetes 向 GitLab Runner Kubernetes 执行器 传递选项。此关键字不适用于其他执行器类型。

关键字类型：作业关键字。你只能在作业中使用它，或在 default 部分 中使用。

支持的值：

一个用于 Kubernetes 执行器的选项哈希，可以包含：

• user：指定容器运行时使用的用户名或 UID。你也可以使用 UID:GID 格式来设置 GID。

仅包含 UID 的 image:kubernetes 示例：

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    kubernetes:
      user: "1001"

同时包含 UID 和 GID 的 image:kubernetes 示例：

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    kubernetes:
      user: "1001:1001"

image:pull_policy

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

Keyword type: 作业关键字。你只能在作业中使用它，或在 default 部分 中使用。

Supported values:

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

Examples of image:pull_policy:

job1:
  script: echo "A single pull policy."
  image:
    name: ruby:3.0
    pull_policy: if-not-present

job2:
  script: echo "Multiple pull policies."
  image:
    name: ruby:3.0
    pull_policy: [always, if-not-present]

Additional details:

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

Related topics:

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

inherit

使用 inherit 来控制默认关键字和变量的继承（相关链接）。

inherit:default

使用 inherit:default 来控制默认关键字的继承（相关链接）。

Keyword type: 作业关键字。你只能在作业中使用它。

Supported values:

• true（默认）或 false 以启用或禁用所有默认关键字的继承。
• 要继承的特定默认关键字列表。

Example of inherit:default:

default:
  retry: 2
  image: ruby:3.0
  interruptible: true

job1:
  script: echo "This job does not inherit any default keywords."
  inherit:
    default: false

job2:
  script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'."
  inherit:
    default:
      - retry
      - image

Additional details:

• 你也可以在一行中列出要继承的默认关键字：default: [keyword1, keyword2]

inherit:variables

使用 inherit:variables 来控制默认变量关键字的继承（相关链接）。

Keyword type: 作业关键字。你只能在作业中使用它。

Supported values:

• true（默认）或 false 以启用或禁用所有默认变量的继承。
• 要继承的特定变量列表。

Example of inherit:variables:

variables:
  VARIABLE1: "This is default variable 1"
  VARIABLE2: "This is default variable 2"
  VARIABLE3: "This is default variable 3"

job1:
  script: echo "This job does not inherit any default variables."
  inherit:
    variables: false

job2:
  script: echo "This job inherits only the two listed default variables. It does not inherit 'VARIABLE3'."
  inherit:
    variables:
      - VARIABLE1
      - VARIABLE2

Additional details:

• 你也可以在一行中列出要继承的默认变量：variables: [VARIABLE1, VARIABLE2]

interruptible

使用 interruptible 来配置 自动取消冗余流水线 功能，以便在同一引用的新提交启动新流水线时，在作业完成前将其取消。如果该功能已禁用，此关键字将不起作用。新流水线必须针对包含新更改的提交。例如，如果你在界面中选择“新建流水线”来运行相同提交的流水线，自动取消冗余流水线 功能将不会生效。

自动取消冗余流水线 功能的行为可以通过 workflow:auto_cancel:on_new_commit 设置进行控制。

关键字类型：作业关键字。你只能将它用作作业的一部分或在 default 部分 中使用。

支持的值：

• true 或 false（默认）。

带有默认行为的 interruptible 示例：

workflow:
  auto_cancel:
    on_new_commit: conservative # the default behavior

stages:
  - stage1
  - stage2
  - stage3

step-1:
  stage: stage1
  script:
    - echo "可以被取消。"
  interruptible: true

step-2:
  stage: stage2
  script:
    - echo "不能被取消。"

step-3:
  stage: stage3
  script:
    - echo "因为 step-2 不能被取消，所以即使设置了 interruptible，这个步骤也永远无法被取消。"
  interruptible: true

在此示例中，新流水线会导致正在运行的流水线：

• 被取消，仅当 step-1 正在运行或等待执行时。
• 不被取消，在 step-2 开始之后。

带有 auto_cancel:on_new_commit:interruptible 设置的 interruptible 示例：

workflow:
  auto_cancel:
    on_new_commit: interruptible

stages:
  - stage1
  - stage2
  - stage3

step-1:
  stage: stage1
  script:
    - echo "可以被取消。"
  interruptible: true

step-2:
  stage: stage2
  script:
    - echo "不能被取消。"

step-3:
  stage: stage3
  script:
    - echo "可以被取消。"
  interruptible: true

在此示例中，新流水线会导致正在运行或等待执行的 step-1 和 step-3 被取消。

其他详细信息：

• 仅当作业可以在启动后被安全取消时，才应设置 interruptible: true，例如构建作业。部署作业通常不应被取消，以避免部分部署。
• 当使用默认行为或 workflow:auto_cancel:on_new_commit: conservative 时：
  • 尚未开始的作业始终被视为 interruptible: true，无论作业配置如何。interruptible 配置仅在作业开始后才被考虑。
  • 只有当所有正在运行的作业都配置为 interruptible: true，或者从未有过配置为 interruptible: false 的作业开始时，运行中 的流水线才会被取消。一旦有配置为 interruptible: false 的作业开始，整个流水线就不再被认为是可中断的。
  • 如果流水线触发了下游流水线，但下游流水线中尚未有 interruptible: false 的作业开始，则下游流水线也会被取消。
• 你可以在流水线的第一阶段添加一个可选的手动作业，并设置 interruptible: false，以允许用户手动阻止流水线被自动取消。用户启动该作业后，流水线将无法通过 自动取消冗余流水线 功能被取消。
• 当与 trigger job 一起使用 interruptible 时：
  • 由触发作业触发的下游流水线永远不会受到触发作业 interruptible 配置的影响。
  • 如果 workflow:auto_cancel 设置为 conservative，触发作业的 interruptible 配置将不起作用。
  • 如果设置为 interruptible，配置为 interruptible: true 的触发作业可以被自动取消。

needs

使用 needs 可不按顺序执行作业。使用 needs 的作业之间的关系可以可视化为一个有向无环图。

你可以忽略阶段顺序，运行一些作业而不等待其他作业完成。多个阶段的作业可以并发运行。

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

支持值：

• 作业数组（最多50个作业）。
• 空数组（[]），用于设置作业在流水线创建后立即开始。

needs 示例：

linux:build:
  stage: build
  script: echo "Building linux..."

mac:build:
  stage: build
  script: echo "Building mac..."

lint:
  stage: test
  needs: []
  script: echo "Linting..."

linux:rspec:
  stage: test
  needs: ["linux:build"]
  script: echo "Running rspec on linux..."

mac:rspec:
  stage: test
  needs: ["mac:build"]
  script: echo "Running rspec on mac..."

production:
  stage: deploy
  script: echo "Running production..."
  environment: production

此示例创建了四条执行路径：

• Linter：lint 作业立即运行，无需等待 build 阶段完成，因为它没有依赖项（needs: []）。
• Linux 路径：linux:rspec 作业在 linux:build 作业完成后立即运行，无需等待 mac:build 完成。
• macOS 路径：mac:rspec 作业在 mac:build 作业完成后立即运行，无需等待 linux:build 完成。
• production 作业在所有之前的作业完成后立即运行：lint、linux:build、linux:rspec、mac:build、mac:rspec。

附加详情：

• 单个作业的 needs 数组中可包含的最大作业数量有限制：
  • 对于 GitLab.com，限制为50。更多信息请参见 issue 350398。
  • 对于 GitLab 自托管版和 GitLab 专用版，默认限制为50。可通过更新 Admin 区域中的 CI/CD 限制更改此限制。
• 如果 needs 指向使用了 parallel 关键字的作业，它会依赖所有并行创建的作业，而不仅仅是其中一个作业。默认情况下，它会下载所有并行作业的制品；若制品名称相同，则会相互覆盖，仅保存最后下载的一个。
  • 若要让 needs 仅指向并行化作业的子集（而非全部并行化作业），请使用 needs:parallel:matrix 关键字。
• 你可以引用与你正在配置的作业处于同一阶段的作业。
• 如果 needs 指向由于 only、except 或 rules 而可能未被添加到流水线的作业，则流水线可能无法创建。使用 needs:optional 关键字来解决流水线创建失败的问题。
• 如果一个流水线中有 needs: [] 的作业和在 .pre 阶段的作业，它们都会在流水线创建后立即启动。needs: [] 的作业立即启动，.pre 阶段的作业也会立即启动。

needs:artifacts

当作业使用 needs 时，默认情况下不再下载之前阶段的所有制品，因为使用 needs 的作业可以在较早阶段完成前启动。使用 needs 时，你只能从 needs 配置中列出的作业下载制品。

使用 artifacts: true（默认）或 artifacts: false 来控制在使用 needs 的作业中何时下载制品。

关键字类型：作业关键字。你只能在作业中使用它。必须与 needs:job 一起使用。

支持值：

• true（默认）或 false。

needs:artifacts 示例：

test-job1:
  stage: test
  needs:
    - job: build_job1
      artifacts: true

test-job2:
  stage: test
  needs:
    - job: build_job2
      artifacts: false

test-job3:
  needs:
    - job: build_job1
      artifacts: true
    - job: build_job2
    - build_job3

在此示例中：

• test-job1 作业下载 build_job1 的制品。
• test-job2 作业不下载 build_job2 的制品。
• test-job3 作业下载所有三个 build_jobs 的制品，因为所有三个所需作业的 artifacts 为 true，或者默认为 true。

附加详情：

• 你不应在同一个作业中同时使用 needs 和 dependencies。

needs:project

使用 needs:project 可从其他管道中的最多五个作业下载工件。工件将从指定引用的最新成功指定作业中下载。若要指定多个作业，请在 needs 关键字下将每个作业作为单独的数组项添加。

如果存在针对该引用运行的管道，带有 needs:project 的作业不会等待管道完成。相反，工件会从指定作业的最新成功运行中下载。

needs:project 必须与 job、ref 和 artifacts 一起使用。

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

支持的值：

• needs:project：包含命名空间和组的完整项目路径。
• job：从中下载工件的作业。
• ref：从中下载工件的引用。
• artifacts：必须为 true 才能下载工件。

needs:project 示例：

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: namespace/group/project-name
      job: build-1
      ref: main
      artifacts: true
    - project: namespace/group/project-name-2
      job: build-2
      ref: main
      artifacts: true