CI/CD YAML 语法参考 - GitLab - GitLab 文档中心

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com，私有化部署

本文档列出了极狐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 配置使用 YAML 格式，因此除非另有说明，关键字的顺序并不重要。

使用 CI/CD 表达式可获得更动态的流水线配置选项。

关键字#

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

用于配置流水线行为的全局关键字：

关键字	描述
default	为作业关键字自定义默认值。
include	从其他 YAML 文件导入配置。
stages	流水线阶段的名称和顺序。
variables	为流水线中的所有作业定义默认 CI/CD 变量。
workflow	控制运行哪些类型的流水线。

头部关键字

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

关键字	描述
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	定义作业阶段。
start_in	将作业执行延迟指定的时长。需要 when: delayed。
tags	用于选择 runner 的标签列表。
timeout	定义自定义的作业级超时，其优先级高于项目范围的设置。
trigger	定义下游流水线触发器。
variables	为各个作业定义 CI/CD 变量。
when	何时运行作业。

不再推荐使用的已弃用关键字。

全局关键字#

有些关键字不是在作业中定义的。这些关键字控制流水线行为或导入额外的流水线配置。

default#

您可以为某些关键字设置全局默认值。每个默认关键字都会复制到每个尚未定义该关键字的作业中。

默认配置不会与作业配置合并。如果作业已经定义了某个关键字，则作业关键字优先，该关键字的默认配置不会被使用。

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

支持的值：以下关键字可以具有自定义默认值：

after_script
artifacts
before_script
cache
hooks
id_tokens
image
interruptible
retry
services
tags

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 将外部 YAML 文件包含到您的 CI/CD 配置中。您可以将一个很长的 .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
include:cache

其他详细信息：

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

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：可选。要从中获取文件的 ref。未指定时默认为项目的 HEAD。可以是分支名称、标签名称或提交 SHA。为避免同名分支和标签之间的歧义，请使用完全限定的 ref，例如 refs/heads/<branch> 或 refs/tags/<tag>。
您可以使用特定的 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: refs/heads/main                           # Git branch, fully qualified
4    file: '/templates/.gitlab-ci-template.yml'
5  - project: 'my-group/my-project'
6    ref: refs/tags/v1.0.0                          # Git tag, fully qualified
7    file: '/templates/.gitlab-ci-template.yml'
8  - project: 'my-group/my-project'
9    ref: main                                      # Git branch or tag, short form
10    file: '/templates/.gitlab-ci-template.yml'
11  - project: 'my-group/my-project'
12    ref: 787123b47f14b552955ca2786bc9542ae66fee5b  # Git SHA
13    file: '/templates/.gitlab-ci-template.yml'

其他详细信息：

include 配置始终基于包含 include 关键字的文件的位置进行评估，而不是基于运行流水线的项目。如果嵌套 include 位于另一个项目的配置文件中，则 include: local 会在该其他项目中查找该文件。
当流水线启动时，会评估通过所有方法包含的 .gitlab-ci.yml 文件配置。该配置是某一时刻的快照，并会持久保存在数据库中。极狐GitLab 不会反映对所引用的 .gitlab-ci.yml 文件配置的任何更改，直到下一个流水线启动。
对于 include:project中的任何私有项目，运行流水线的用户必须至少具有报告者角色。对于内部项目，任何经过身份验证的非外部用户都可以访问所包含的文件。对于公开项目，无需成员身份。如果用户对所包含的项目没有足够的权限，则会显示 not found or access denied 错误。
包含另一个项目的 CI/CD 配置文件时要小心。CI/CD 配置文件更改时不会触发任何流水线或通知。从安全角度来看，这类似于拉取第三方依赖项。对于 ref，请考虑：
- 使用特定的 SHA 哈希，这应该是最稳定的选项。使用完整的 40 字符 SHA 哈希以确保引用所需的提交，因为为 ref 使用短 SHA 哈希可能会产生歧义。
- 使用完全限定的 ref，例如 refs/heads/<branch> 或 refs/tags/<tag>，而不是像 main 这样的短名称。短名称可能同时匹配分支和标签。如果两者都存在，则会从标签中获取文件，即使您本意是从同名的受保护分支中包含该文件。
- 对另一个项目中的 ref 同时应用受保护分支和受保护标签规则。受保护标签和分支在更改之前更有可能经过变更管理流程。

include:remote#

使用 include:remote 和完整 URL 来包含来自不同位置的文件。

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

支持的值：

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

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

include:remote 示例：

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

其他详细信息：

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

include:template#

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

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

支持的值：

CI/CD 模板的文件名，例如 Auto-DevOps.gitlab-ci.yml。
您可以使用特定的 CI/CD 变量。

include:template 示例：

yaml
# File sourced from the GitLab template collection
include:
  - template: Auto-DevOps.gitlab-ci.yml

多个 include:template 文件：

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

其他详细信息：

所有模板都可以在 lib/gitlab/ci/templates中查看。并非所有模板都设计为与 include:template 一起使用，因此在使用某个模板之前请先查看模板注释。
所有嵌套 include 都以公开用户身份在无上下文的情况下执行，因此您只能包含公开项目或模板。嵌套 include 的 include 部分中没有可用的变量。

include:inputs#

当所包含的配置使用 spec:inputs 并添加到流水线时，使用 include: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://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'
    integrity: 'sha256-L3/GAoKaw0Arw6hDCKeKQlV1QPEgHYxGBHsH4zG1IY8='

include:cache#

将 cache 与 include:remote 一起使用，以缓存获取的远程文件内容并减少 HTTP 请求。启用后，远程文件会在指定的生存时间（TTL）内被缓存。此缓存可提高复用相同远程 include 的配置的流水线性能。

在设置缓存时长时，请考虑性能与新鲜度之间的权衡。较长的缓存时长可提高性能，但如果远程文件频繁更改，可能会使用过时的内容。

未定义 cache 时，每次都会获取远程文件。

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

支持的值：

true：启用缓存，默认生存时间（TTL）为 1 小时。
时长（字符串）：有效的 TTL 时长字符串使用时间单位，例如 minutes、hours 或 days（最小 1 minute）。

include:cache 示例：

yaml
include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/sample1.gitlab-ci.yml'
    cache: true
  - remote: 'https://gitlab.com/example-project/-/raw/main/sample2.gitlab-ci.yml'
    cache: '1 day'

其他详细信息：

缓存仅适用于 include:remote。
远程文件被缓存后，即使远程文件内容发生更改，也会继续使用缓存版本，直到 TTL 过期。
如果您将 integrity 与 cache 一起使用，则每次流水线运行时都会执行完整性检查，即使使用的是缓存内容。

stages#

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

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

.pre
build
test
deploy
.post

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

同一阶段中的作业并行运行。
下一阶段中的作业在上一阶段的作业成功完成后运行。

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

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

stages 示例：

yaml
stages:
  - build
  - test
  - deploy

在此示例中：

build中的所有作业并行执行。
如果 build中的所有作业都成功，则 test 作业并行执行。
如果 test中的所有作业都成功，则 deploy 作业并行执行。
如果 deploy中的所有作业都成功，则流水线被标记为 passed。

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

其他详细信息：

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

相关主题：

要使作业更早启动并忽略阶段顺序，请使用 needs 关键字。

workflow#

使用 workflow 控制流水线行为。

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

相关主题：

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  # Default when not defined.
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'  # A default is not required
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  # For default branch pipelines, use the default name

其他详细信息：

如果名称为空字符串，则不会为流水线分配名称。仅由 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中使用它们，因为这可能会在将来导致语法失败。有关更多详细信息，请参阅议题 436473。

相关主题：

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"  # Override globally-defined DEPLOY_VARIABLE
9    - if: $CI_COMMIT_BRANCH =~ /feature/
10      variables:
11        IS_A_FEATURE: "true"                  # Define a new variable.
12    - if: $CI_COMMIT_BRANCH                   # Run the pipeline in other cases
13
14job1:
15  variables:
16    DEPLOY_VARIABLE: "job1-default-deploy"
17  rules:
18    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
19      variables:                                   # Override DEPLOY_VARIABLE defined
20        DEPLOY_VARIABLE: "job1-deploy-production"  # at the job level.
21    - when: on_success                             # Run the job in other cases
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                  # Run the pipeline in other cases
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 部分，以控制包含该文件的流水线的行为。

规范必须在配置文件的顶部声明，位于通过 --- 与配置的其余部分分隔开的头部部分中。

spec:inputs#

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

使用插值格式 $[[ inputs.input-id ]] 引用头部部分之外的值。输入会在流水线创建期间获取配置时被求值和插值。使用 inputs 时，插值会在配置与 .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: ''
8---
9# The pipeline configuration would follow...

在此示例中：

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

其他详细信息：

当输入出现以下情况时，流水线会因验证错误而失败：
- 同时使用 default 和 options，但默认值不是所列选项之一。
- 同时使用 default 和 regex，但默认值与正则表达式不匹配。
- 值与 type 不匹配。

spec:inputs:description#

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

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

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

spec:inputs:description 示例：

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

spec:inputs:options#

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

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

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

spec:inputs:options 示例：

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

在此示例中：

environment 是必填的，必须使用列表中的某个值来定义。

其他详细信息：

在以下情况下，流水线会因验证错误而失败：
- 输入同时使用 options 和 default，但默认值不是所列选项之一。
- 任何输入选项与 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+)?$
5---
6# 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:rules#

使用 spec:inputs:rules 根据其他输入的值，为某个输入定义有条件的 options 和 default 值。

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

支持的值：规则对象的数组。每条规则可以具有：

if：用于检查输入值的条件表达式，使用 $[[ inputs.input-id ]] 语法。
options：输入的允许值数组。
default：当此规则匹配时输入的默认值。使用 default: null 允许用户为输入输入自己的值。

spec:inputs:rules 示例：

yaml
1spec:
2  inputs:
3    environment:
4      options: ['development', 'production']
5      default: 'development'
6
7    instance_type:
8      description: 'VM instance size'
9      rules:
10        - if: $[[ inputs.environment ]] == 'development'
11          options: ['small', 'medium']
12          default: 'small'
13        - if: $[[ inputs.environment ]] == 'production'
14          options: ['large', 'xlarge']
15          default: 'large'
16---
17
18deploy:
19  script: echo "Deploying $[[ inputs.instance_type ]] instance"

在此示例中，当 environment 为 development 时，用户只能选择 small 或 medium 实例。当 environment 为 production 时，只有 large 或 xlarge 实例可用。

其他详细信息：

规则按顺序求值。使用第一个具有匹配 if 条件的规则。
没有 if 条件的规则在没有其他规则匹配时充当回退规则。
回退规则必须定义至少包含一个值的 options。
所有具有 options的规则还必须定义存在于 options 列表中的 default 值。
对于同一个输入，不能同时使用 rules 和顶层 options 或 default。

相关主题：

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

spec:inputs:type#

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

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

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

array，接受输入的数组。
string，接受字符串输入（未定义时的默认值）。
number，仅接受数值输入。
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
12---
13# The pipeline configuration would follow...

spec:include#

使用 spec:include 包含来自其他文件的外部输入定义。您可以在多个流水线配置之间共享和复用输入定义。

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

支持的值：include 位置的数组。仅支持 local、remote 和 project include。

spec:include 示例：

yaml
1spec:
2  include:
3    - local: /shared-inputs.yml
4  inputs:
5    environment:
6      default: production
7---
8
9deploy:
10  script: echo "Deploying to $[[ inputs.environment ]]"

包含来自不同来源的多个 include：

yaml
1spec:
2  include:
3    - local: /base-inputs.yml
4    - remote: 'https://example.com/ci/common-inputs.yml'
5    - project: 'my-group/shared-configs'
6      ref: main
7      file: '/ci/team-inputs.yml'
8  inputs:
9    environment:
10      default: production
11---
12
13deploy:
14  script: echo "Deploying to $[[ inputs.environment ]]"

其他详细信息：

您不能在 CI/CD 组件中使用 spec:include。
外部输入文件必须只包含 inputs 键。其他键会导致验证错误。
先合并外部输入，然后应用内联输入。
内联输入不能与所包含的输入同名。
当您包含多个输入文件时，它们会按指定的顺序合并。
支持 local、remote 和 project include 类型。不支持 template、component 或 artifact include。
include 位置基于包含 spec 部分的文件的代码仓库和 ref 进行解析，而不是基于包含它的文件。 local 位置相对于声明 spec:include的文件而言是本地的。
您不能在通过 include:remote 或 include:template 添加的文件中使用 local 位置，因为这些文件没有可供解析的代码仓库。请改用 include:project。

相关主题：

使用来自外部文件的输入。

spec:component#

使用 spec:component 定义在 CI/CD 组件中可用于插值的组件上下文数据。

组件上下文提供有关组件本身的元数据，例如其名称、版本和提交 SHA。这允许组件模板动态引用其自身的元数据。

使用插值格式 $[[ component.field-name ]] 在组件模板中引用组件上下文值。

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

支持的值：字符串数组。每个字符串必须是以下之一：

name：组件路径中指定的组件名称。
sha：组件的提交 SHA。
version：从目录资源解析出的语义版本。在以下情况下返回 null：
- 该组件不是目录资源。
- 引用是分支名称或提交 SHA（不是已发布的版本）。
reference：组件路径中 @ 之后指定的原始引用。例如，1.0、~latest、分支名称或提交 SHA。

spec:component 示例：

yaml
1spec:
2  component: [name, version, reference]
3  inputs:
4    stage:
5      default: build
6---
7
8build-image:
9  stage: $[[ inputs.stage ]]
10  image: registry.example.com/$[[ component.name ]]:$[[ component.version ]]
11  script:
12    - echo "Building with component version $[[ component.version ]]"
13    - echo "Component reference: $[[ component.reference ]]"

其他详细信息：

在使用以下内容时，version 字段会解析为实际的语义版本：
- 完整版本，如 @1.0.0（返回 1.0.0）
- 部分版本，如 @1.0（返回最新的匹配版本，例如 1.0.2）
- @~latest（返回最新版本）
reference 字段始终返回 @ 之后指定的确切值：
- @1.0 返回 1.0（而 version 可能返回 1.0.2）
- @~latest 返回 ~latest（而 version 返回实际版本号）
- @abc123 返回 abc123（而 version 返回 null）

相关主题：

在组件中使用组件上下文。

spec:description#

使用 spec:description 提供组件的简短描述。该描述会显示在 CI/CD Catalog 的组件详情页面上，位于输入表格上方。

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

支持的值：描述组件的字符串。

spec:description 示例：

yaml
1spec:
2  description: "A description of the component visible to users in the CI/CD Catalog."
3  inputs:
4    stage:
5      default: test
6---
7scan-job:
8  stage: $[[ inputs.stage ]]
9  script: ./run-scan.sh

作业关键字#

以下主题说明如何使用关键字配置 CI/CD 流水线。

after_script#

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

作业在 before_script 或 script 部分仍在运行时被取消。
作业以 script_failure 失败类型失败，但不包括其他失败类型。

作业配置和默认配置不会合并在一起。如果流水线定义了 default:after_script，并且该作业也定义了 after_script，则作业配置优先，默认配置不会被使用。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

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

单行命令。
拆分为多行的长命令。
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 命令分开。因此，它们：

会将当前工作目录重置为默认值（根据定义 runner 如何处理 Git 请求的变量）。
无法访问由 before_script 或 script中定义的命令所做的更改，包括：
- 在 script 脚本中导出的命令别名和变量。
- 工作树之外的更改（取决于 runner 执行器），例如由 before_script 或 script 脚本安装的软件。
具有单独的超时。默认值为 5 分钟，可以通过 RUNNER_AFTER_SCRIPT_TIMEOUT 变量进行配置。
不会影响作业的退出代码。如果 script 部分成功，而 after_script 超时或失败，则作业以代码 0（Job Succeeded）退出。
对于超时的作业：
- 默认情况下，after_script 命令不会执行。
- 您可以配置超时值，通过设置不超过作业超时的适当 RUNNER_SCRIPT_TIMEOUT 和 RUNNER_AFTER_SCRIPT_TIMEOUT 值，确保 after_script 运行。
在顶层（而不是在 default 部分中）使用 after_script 已被弃用。

执行时机和文件包含：

after_script 命令在缓存和产物上传操作之前执行。

如果您配置了产物收集：
- 在 after_script中创建或修改的文件会包含在产物中。
- 在 after_script中所做的更改会包含在缓存上传中。
after_script 在指定的缓存或产物路径中创建或修改的任何文件都会被捕获并上传。您可以将此时机用于以下场景：
- 在主脚本之后生成测试报告或覆盖率数据。
- 创建摘要文件或日志。
- 对构建输出进行后处理。

在以下示例中，唯一未被包含的文件是在产物或缓存上传阶段之后创建或修改的文件：

yaml
1job:
2  script:
3    - echo "main" > output.txt
4    - build_something
5
6  after_script:
7    - echo "modified in after_script" >> output.txt  # This WILL be in the artifact
8    - generate_test_report > report.html            # This WILL be in the artifact
9
10  artifacts:
11    paths:
12      - output.txt
13      - report.html
14
15  cache:
16    paths:
17      - output.txt  # Will include the "modified in after_script" line

有关更多信息，请参阅作业执行流程。

相关主题：

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

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 并行运行：

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

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 配置中定义的作业的产物。

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

作业配置和默认配置不会合并在一起。如果流水线定义了 default:artifacts，而作业也定义了 artifacts，则作业配置优先，不使用默认配置。

详细了解产物。

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

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

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

其他详细信息：

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

相关主题：

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

artifacts:exclude#

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

artifacts:exclude 示例：

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

yaml
job:
  artifacts:
    expire_in: 1 week

其他详细信息：

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

artifacts:expose_as#

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

artifacts:expose_as 示例：

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

其他详细信息：

每个作业只能使用一次 expose_as，每个合并请求最多 10 个作业。
不支持 Glob 模式。
产物始终会发送到极狐GitLab。它们会显示在 UI 中，除非 artifacts:paths 值：
- 使用 CI/CD 变量。
- 定义了一个目录，但不以 / 结尾。例如，directory/ 可与 artifacts:expose_as 一起使用，但 directory 不行。
如果 artifacts:paths 仅包含单个文件，则链接会直接打开该文件。在所有其他情况下，链接会打开产物浏览器。
默认情况下会下载链接的文件。如果启用了 GitLab Pages，您可以直接在浏览器中预览某些产物文件扩展名。有关详细信息，请参阅浏览产物归档的内容。

相关主题：

在合并请求 UI 中公开作业产物。

artifacts:name#

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

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

产物归档的名称。支持 CI/CD 变量（参见说明）。必须与 artifacts:paths 结合使用。

artifacts:name 示例：

要创建以当前作业命名的归档：

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

相关主题：

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

artifacts:public#

artifacts:public 现已被 artifacts:access 取代，后者有更多选项。

使用 artifacts:public 控制公共流水线中的作业产物是否可供匿名用户，或访客和报告者角色通过极狐GitLab UI 和 API 下载。

此选项仅影响极狐GitLab UI 和 API 访问。使用作业令牌的 CI/CD 作业仍可通过 runner API 访问产物，无论此设置如何。要限制作业令牌访问，请将项目的 CI/CD 可见性设置配置为仅项目成员。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

true（默认）：公共流水线中作业的产物可供任何人下载，包括匿名用户，或访客和报告者角色。
false：作业中的产物仅可供具有开发者、维护者或所有者角色的用户下载。

artifacts:public 示例：

yaml
job:
  artifacts:
    public: false

artifacts:access#

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

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

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

支持的值：

all（默认）：公共流水线中作业的产物可供任何人下载，包括匿名、访客和报告者用户。
developer：作业中的产物仅可供具有开发者、维护者或所有者角色的用户下载。
maintainer：作业中的产物仅可供具有维护者或所有者角色的用户下载。
none：作业中的产物不可供任何人下载。

artifacts:access 示例：

yaml
job:
  artifacts:
    access: 'developer'

其他详细信息：

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

artifacts:reports#

使用 artifacts:reports 收集作业中包含的模板生成的产物。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

请参阅可用的产物报告类型列表。

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

其他详细信息：

不支持使用来自子流水线的产物在父流水线中合并报告。有关详细信息，请参阅史诗 8205。
要浏览和下载报告输出文件，请包含 artifacts:paths 关键字。这会两次上传和存储该产物。
为 artifacts: reports 创建的产物始终会上传，无论作业结果（成功或失败）如何。您可以使用 artifacts:expire_in 为产物设置过期日期。

artifacts:untracked#

使用 artifacts:untracked 将所有 Git 未跟踪文件添加为产物（连同 artifacts:paths中定义的路径）。artifacts:untracked 忽略代码仓库 .gitignore中的配置，因此 .gitignore中匹配的产物也会被包含。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

artifacts:untracked 示例：

保存所有 Git 未跟踪文件：

yaml
job:
  artifacts:
    untracked: true

相关主题：

将未跟踪文件添加到产物。

artifacts:when#

使用 artifacts:when 在作业失败时或尽管失败也上传产物。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

artifacts:when 示例：

yaml
job:
  artifacts:
    when: on_failure

其他详细信息：

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

before_script#

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

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

单行命令。
拆分为多行的长命令。
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."

其他详细信息：

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

相关主题：

将 before_script 与 default 一起使用来定义应在所有作业的 script 命令之前运行的默认命令数组。
- 作业配置和默认配置不会合并在一起。如果流水线定义了 default:before_script，而作业也定义了 before_script，则作业配置优先，不使用默认配置。
您可以忽略非零退出码。
将颜色代码与 before_script 一起使用使作业日志更易于查看。
创建自定义可折叠部分以简化作业日志输出。

cache#

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

缓存：

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

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

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

作业配置和默认配置不会合并在一起。如果流水线定义了 default:cache，而作业也定义了 cache，则作业配置优先，不使用默认配置。

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

在顶层使用 cache，但不在 default 部分中使用，已弃用。

cache:paths#

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

相对于项目目录（$CI_PROJECT_DIR）的路径数组。您可以使用 glob 和 doublestar.Glob 模式通配符。

支持 CI/CD 变量。

cache:paths 示例：

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

yaml
1rspec:
2  script:
3    - echo "This job uses a cache."
4  cache:
5    key: binaries-cache
6    paths:
7      - binaries/*.apk
8      - .config

其他详细信息：

cache:paths 关键字会包含文件，即使它们是未跟踪的或位于您的 .gitignore 文件中。

相关主题：

有关更多 cache:paths 示例，请参阅 CI/CD 缓存示例。

cache:key#

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

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

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

cache:key 示例：

yaml
1cache-job:
2  script:
3    - echo "This job uses a cache."
4  cache:
5    key: binaries-cache-$CI_COMMIT_REF_SLUG
6    paths:
7      - binaries/

其他详细信息：

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

相关主题：

您可以指定一个回退缓存键，以便在找不到指定的 cache:key 时使用。
您可以在单个作业中使用多个缓存键。
有关更多 cache:key 示例，请参阅 CI/CD 缓存示例。

cache:key:files#

此功能的可用性由功能标志控制。

使用 cache:key:files 在指定文件的内容更改时生成新的缓存键。如果内容保持不变，则缓存键在各分支和流水线之间保持一致。您可以重用缓存并减少重建次数，从而加快后续流水线运行速度。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

最多 10 个文件路径或模式的数组。

不支持 CI/CD 变量。

cache:key:files 示例：

yaml
1cache-job:
2  script:
3    - echo "This job uses a cache."
4  cache:
5    key:
6      files:
7        - Gemfile.lock
8        - package.json
9    paths:
10      - vendor/ruby
11      - node_modules

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

其他详细信息：

缓存 key 是根据所列文件内容计算的 SHA。如果文件不存在，则在键计算中忽略它。如果指定的文件都不存在，则回退键为 default。
可以使用像 **/package.json 这样的通配符模式。
最多可以指定 10 个文件。

cache:key:files_commits#

使用 cache:key:files_commits 在指定文件的最新提交更改时生成新的缓存键。cache:key:files_commits 缓存键会在指定文件有新提交时更改，即使文件内容保持不变。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

cache:key:files_commits 示例：

yaml
1cache-job:
2  script:
3    - echo "This job uses a commit-based cache."
4  cache:
5    key:
6      files_commits:
7        - package.json
8        - yarn.lock
9    paths:
10      - node_modules

此示例基于 package.json 和 yarn.lock的提交历史创建缓存。如果这些文件的提交历史更改，则会计算新的缓存键并创建新的缓存。

其他详细信息：

缓存 key 是根据每个指定文件的最新提交计算的 SHA。
如果文件不存在，则在键计算中忽略它。
如果指定的文件都不存在，则回退键为 default。
不能在同一缓存配置中与 cache:key:files 一起使用。

cache:key:prefix#

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

cache:key:prefix 示例：

yaml
1rspec:
2  script:
3    - echo "This rspec job uses a cache."
4  cache:
5    key:
6      files:
7        - Gemfile.lock
8      prefix: $CI_JOB_NAME
9    paths:
10      - vendor/ruby

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

其他详细信息：

如果 cache:key:files中没有任何文件在任何提交中更改，则会将前缀添加到 default 键。

cache:untracked#

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

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

如果作业下载以下内容，缓存未跟踪文件可能会创建意外的大型缓存：

依赖项，如 gems 或 node modules，它们通常是未跟踪的。
来自不同作业的产物。从产物中提取的文件默认是未跟踪的。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

true 或 false（默认）。

cache:untracked 示例：

yaml
rspec:
  script: test
  cache:
    untracked: true

其他详细信息：

您可以将 cache:untracked 与 cache:paths 结合使用，以缓存所有未跟踪文件以及配置路径中的文件。使用 cache:paths 缓存任何特定文件，包括已跟踪文件或工作目录之外的文件，并使用 cache: untracked 同时缓存所有未跟踪文件。例如：
```
yaml
1rspec:
2  script: test
3  cache:
4    untracked: true
5    paths:
6      - binaries/
```
在此示例中，作业缓存代码仓库中的所有未跟踪文件以及 binaries/ 中的所有文件。如果 binaries/ 中有未跟踪文件，则它们会被这两个关键字覆盖。

cache:unprotect#

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

当设置为 true 时，无权访问受保护分支的用户可以读取和写入受保护分支使用的缓存键。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

true 或 false（默认）。

cache:unprotect 示例：

yaml
rspec:
  script: test
  cache:
    unprotect: true

cache:when#

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

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

cache:when 示例：

yaml
1rspec:
2  script: rspec
3  cache:
4    paths:
5      - rspec/
6    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 示例：

yaml
1prepare-dependencies-job:
2  stage: build
3  cache:
4    key: gems
5    paths:
6      - vendor/bundle
7    policy: push
8  script:
9    - echo "This job only downloads dependencies and builds the cache."
10    - echo "Downloading dependencies..."
11
12faster-test-job:
13  stage: test
14  cache:
15    key: gems
16    paths:
17      - vendor/bundle
18    policy: pull
19  script:
20    - echo "This job script uses the cache, but does not update it."
21    - echo "Running tests..."

相关主题：

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

cache:fallback_keys#

使用 cache:fallback_keys 指定一个键列表，以便在 cache:key 找不到缓存时尝试从中恢复缓存。缓存按 fallback_keys 部分中指定的顺序检索。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

缓存键数组

cache:fallback_keys 示例：

yaml
1rspec:
2  script: rspec
3  cache:
4    key: gems-$CI_COMMIT_REF_SLUG
5    paths:
6      - rspec/
7    fallback_keys:
8      - gems
9    when: 'always'

coverage#

使用 coverage 和自定义正则表达式配置如何从作业输出中提取代码覆盖率。极狐GitLab 会在合并请求小组件、流水线作业列表和分析图表中显示匹配的百分比。

支持的值：

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

coverage 示例：

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

在此示例中：

极狐GitLab 检查作业日志中是否有与正则表达式匹配的内容。像 Code coverage: 67.89% of lines covered 这样的行会匹配。
然后极狐GitLab 检查匹配的片段是否与 \d+(?:\.\d+)? 匹配，以提取数字。示例正则表达式匹配 67.89。

其他详细信息：

如果作业输出中有多行匹配，则使用最后一行。
如果单行中有多个匹配项，则使用最后一个匹配项。
如果匹配的片段中有多个覆盖率数字，则使用第一个数字。
移除前导零。
不记录来自子流水线的覆盖率输出。请参阅议题 280818。
要在合并请求差异中显示逐行差异注释，请单独配置 artifacts:reports:coverage_report。配置其中一个不会启用另一个。

相关主题：

dast_configuration#

Tier: 旗舰版

Offering: JihuLab.com，私有化部署

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

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

支持的值：各一个 site_profile 和 scanner_profile。

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

dast_configuration 示例：

yaml
1stages:
2  - build
3  - dast
4
5include:
6  - template: DAST.gitlab-ci.yml
7
8dast:
9  dast_configuration:
10    site_profile: "Example Co"
11    scanner_profile: "Quick Passive Test"

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

其他详细信息：

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

相关主题：

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

dependencies#

使用 dependencies 关键字定义要从中获取产物的特定作业列表。指定的作业必须都在早期阶段。您也可以将作业设置为完全不下载任何产物。

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

要从同一阶段中的作业获取产物，必须使用 needs:artifacts。您不应在同一作业中将 dependencies 与 needs 结合使用。

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

支持的值：

要从中获取产物的作业名称。
空数组（[]），用于将作业配置为不下载任何产物。

dependencies 示例：

yaml
1build mac:
2  stage: build
3  script: make build:mac
4  artifacts:
5    paths:
6      - binaries/
7
8build linux:
9  stage: build
10  script: make build:linux
11  artifacts:
12    paths:
13      - binaries/
14
15test mac:
16  stage: test
17  script: make test:mac
18  dependencies:
19    - build mac
20
21test linux:
22  stage: test
23  script: make test:linux
24  dependencies:
25    - build linux
26
27deploy:
28  stage: deploy
29  script: make deploy
30  environment: production

在此示例中，两个作业有产物：build mac 和 build linux。执行 test mac 时，会在构建上下文中下载并提取来自 build mac的产物。test linux 和来自 build linux的产物也是如此。

由于阶段优先级，deploy 作业会下载所有先前作业的产物。

其他详细信息：

如果较早的作业不生成产物，或者是未运行的手动作业，则依赖作业仍会运行，并且不会生成错误。
如果依赖作业的产物已过期或已删除，则该作业会失败。

environment#

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

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

支持的值：作业部署到的环境名称，采用以下格式之一：

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

environment 示例：

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

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

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 关键字指定作业与环境交互的方式。

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

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

值	描述
start	默认值。表示作业启动环境。部署在作业启动后创建。
prepare	表示作业仅准备环境。它不会触发部署。详细了解准备环境。
stop	表示作业停止环境。详细了解停止环境。
verify	表示作业仅验证环境。它不会触发部署。详细了解验证环境。
access	表示作业仅访问环境。它不会触发部署。详细了解访问环境。

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。每次部署 review app 时，该生命周期也会重置为 1 day。

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

相关主题：

环境自动停止文档。

environment:kubernetes#

使用 kubernetes 关键字为环境配置 Kubernetes 仪表板和极狐GitLab 管理的 Kubernetes 资源。

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

支持的值：

agent：一个字符串，指定极狐GitLab Kubernetes Agent。格式为 path/to/agent/project:agent-name。如果 agent 连接到运行流水线的项目，请使用 $CI_PROJECT_PATH:agent-name。
dashboard:namespace：一个字符串，表示部署环境的 Kubernetes 命名空间。命名空间必须与 agent 关键字一起设置。namespace 已弃用。
dashboard:flux_resource_path：一个字符串，表示 Flux 资源的完整路径，例如 HelmRelease。Flux 资源必须与 agent 和 dashboard:namespace 关键字一起设置。flux_resource_path 已弃用。
managed_resources：一个哈希，带有 enabled 关键字，用于为环境配置极狐GitLab 管理的 Kubernetes 资源。
- managed_resources:enabled：一个布尔值，表示是否为环境启用极狐GitLab 管理的 Kubernetes 资源。
dashboard：一个哈希，带有 dashboard:namespace 和 dashboard:flux_resource_path 关键字，用于为环境配置 Kubernetes 仪表板。

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      dashboard:
9        namespace: my-namespace
10        flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

禁用受管资源时的 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      managed_resources:
9        enabled: false
10      dashboard:
11        namespace: my-namespace
12        flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

此配置：

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

其他详细信息：

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

environment:deployment_tier#

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

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

支持的值：以下之一：

production
staging
testing
development
other
CI/CD 变量，包括预定义变量、项目变量、群组变量、实例变量，或在 .gitlab-ci.yml 文件中定义的变量。您不能使用在 script 部分中定义的变量。

environment:deployment_tier 示例：

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

其他详细信息：

从此作业定义创建的环境会根据此值分配一个层级。
如果稍后添加此值，现有环境的层级不会更新。现有环境必须使用 Environments 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 访问此环境。

常见用例是为分支创建动态环境并将其用作 review app。您可以在 https://gitlab.com/gitlab-examples/review-apps-nginx/ 看到一个使用 review app 的示例。

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 指定在作业执行的某些阶段（例如在检索 Git 代码仓库之前）在 runner 上执行的命令列表。

作业配置和默认配置不会合并在一起。如果流水线定义了 default:hooks，而作业也定义了 hooks，则作业配置优先，不使用默认配置。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

钩子及其命令的哈希。可用的钩子：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 配置

identity#

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com

Status: 测试版

此功能处于测试版。

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

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

支持的值：一个标识符。支持的提供商：

google_cloud：Google Cloud。必须使用 Google Cloud IAM 集成进行配置。

identity 示例：

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

相关主题：

id_tokens#

使用 id_tokens 创建 ID 令牌以向第三方服务进行身份验证。以这种方式创建的所有 JWT 都支持 OIDC 身份验证。必需的 aud 子关键字用于为 JWT 配置 aud 声明。

作业配置和默认配置不会合并在一起。如果流水线定义了 default:id_tokens，而作业也定义了 id_tokens，则作业配置优先，不使用默认配置。

支持的值：

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

id_tokens 示例：

yaml
1job_with_id_tokens:
2  id_tokens:
3    ID_TOKEN_1:
4      aud: https://vault.example.com
5    ID_TOKEN_2:
6      aud:
7        - https://gcp.com
8        - https://aws.com
9    SIGSTORE_ID_TOKEN:
10      aud: sigstore
11  script:
12    - command_to_authenticate_with_vault $ID_TOKEN_1
13    - command_to_authenticate_with_aws $ID_TOKEN_2
14    - command_to_authenticate_with_gcp $ID_TOKEN_2

相关主题：

image#

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

作业配置和默认配置不会合并在一起。如果流水线定义了 default:image，而作业也定义了 image，则作业配置优先，不使用默认配置。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：镜像名称，如果需要，还包括镜像仓库路径，采用以下格式之一：

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

支持 CI/CD 变量（参见说明）。

image 示例：

yaml
1default:
2  image: ruby:3.0
3
4rspec:
5  script: bundle exec rspec
6
7rspec 2.7:
8  image: registry.example.com/my-group/my-project/ruby:2.7
9  script: bundle exec rspec

在此示例中，ruby:3.0 镜像是流水线中所有作业的默认镜像。rspec 2.7 作业不使用默认值，因为它用作业特定的 image 部分覆盖了默认值。

其他详细信息：

在顶层使用 image，但不在 default 部分中使用，已弃用。

相关主题：

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

image:name#

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：镜像名称，如果需要，还包括镜像仓库路径，采用以下格式之一：

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

支持 CI/CD 变量（参见说明）。

image:name 示例：

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

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

相关主题：

覆盖镜像的入口点。

image:docker#

使用 image:docker 将选项传递给使用 Docker 执行器或 Kubernetes 执行器的 runner。此关键字不适用于其他执行器类型。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

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

image:docker 示例：

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

其他详细信息：

image:docker:platform 映射到 docker pull --platform 选项。
image:docker:user 映射到 docker run --user 选项。
使用 Docker 执行器时，要运行针对与 runner 主机不同架构构建的镜像，主机必须注册有 binfmt_misc的模拟支持。例如，要安装 QEMU 模拟器，请在主机上运行 docker run --privileged --rm tonistiigi/binfmt --install all。如果没有模拟支持，作业会失败并显示 exec format error 消息。在极狐GitLab Runner 19.1 及更早版本中，与主机不匹配的 platform 值可能会被静默忽略，容器会改为使用主机架构运行。

image:kubernetes#

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

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

仅使用 UID 的 image:kubernetes 示例：

yaml
1arm-sql-job:
2  script: echo "Run sql tests"
3  image:
4    name: super/sql:experimental
5    kubernetes:
6      user: "1001"

同时使用 UID 和 GID 的 image:kubernetes 示例：

yaml
1arm-sql-job:
2  script: echo "Run sql tests"
3  image:
4    name: super/sql:experimental
5    kubernetes:
6      user: "1001:1001"

image:pull_policy#

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

image:pull_policy 示例：

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

其他详细信息：

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

相关主题：

inputs#

使用 inputs 为作业定义类型化且经过验证的输入。作业输入可以在手动运行或重试作业时覆盖。

作业输入是提供类型安全和验证的参数。与 CI/CD 变量不同，在运行或重试作业时只能指定作业中明确定义的输入。所有作业输入名称都必须预定义。

使用 ${{ job.inputs.INPUT_NAME }} Moa 表达式语法引用作业输入值。

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

支持的值：

输入名称的哈希，其中每个输入使用一个或多个子键进行配置：

default（必需）
type
options
description
regex

inputs 示例：

yaml
1test_job:
2  inputs:
3    test_suite:
4      default: unit
5      description: Which test suite to run
6      options: [unit, integration, e2e]
7    parallel_count:
8      type: number
9      default: 5
10      description: Number of parallel test runners
11    verbose:
12      type: boolean
13      default: false
14      description: Enable verbose test output
15  script:
16    - 'echo "Running ${{ job.inputs.test_suite }} tests"'
17    - 'if [ "${{ job.inputs.verbose }}" == "true" ]; then export TEST_VERBOSE=1; fi'
18    - ./run_tests.sh --suite ${{ job.inputs.test_suite }} --parallel ${{ job.inputs.parallel_count }}

其他详细信息：

作业输入在创建作业时以及您尝试使用新输入值重试作业时进行验证。如果验证失败，作业不会启动。
作业输入的作用域限定在定义它们的作业中，其他作业无法访问。
有关支持作业输入的关键字的完整列表，请参阅可以使用作业输入的位置。

inputs:default#

所有作业输入都必须使用 default 定义默认值。

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

支持的值：与输入的 type 匹配的任何值。

inputs:default 示例：

yaml
1test_job:
2  inputs:
3    environment:
4      default: staging
5    timeout:
6      type: number
7      default: 30

inputs:type#

使用 type 定义输入值的数据类型。

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

支持的值：

string（默认）
number
boolean
array。

inputs:type 示例：

yaml
1test_job:
2  inputs:
3    count:
4      type: number
5      default: 5
6    enabled:
7      type: boolean
8      default: true

inputs:description#

使用 description 提供有关输入用途的信息。描述不影响输入的行为。

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

支持的值：一个字符串。

inputs:description 示例：

yaml
deploy_job:
  inputs:
    environment:
      default: staging
      description: Target deployment environment

inputs:options#

使用 options 指定输入的允许值列表。

输入值必须与列出的选项之一完全匹配（区分大小写）。如果值与选项不匹配，则验证失败。

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

支持的值：允许值的数组。

inputs:options 示例：

yaml
deploy_job:
  inputs:
    environment:
      default: staging
      options: [development, staging, production]

inputs:regex#

使用 regex 指定输入值必须匹配的正则表达式模式。

如果值与正则表达式不匹配，则验证失败。

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

支持的值：一个正则表达式字符串。

inputs:regex 示例：

yaml
deploy_job:
  inputs:
    version:
      default: v1.0.0
      regex: ^v\d+\.\d+\.\d+$

在此示例中，输入值 v1.1.1 通过正则表达式验证，但输入 v1.1.1-beta 不通过。

inherit#

使用 inherit 来控制默认关键字和变量的继承。

inherit:default#

使用 inherit:default 来控制默认关键字的继承。

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

支持的值：

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

inherit:default 示例：

yaml
1default:
2  retry: 2
3  image: ruby:3.0
4  interruptible: true
5
6job1:
7  script: echo "This job does not inherit any default keywords."
8  inherit:
9    default: false
10
11job2:
12  script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'."
13  inherit:
14    default:
15      - retry
16      - image

其他详细信息：

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

inherit:variables#

使用 inherit:variables 来控制默认变量关键字的继承。

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

支持的值：

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

inherit:variables 示例：

yaml
1variables:
2  VARIABLE1: "This is default variable 1"
3  VARIABLE2: "This is default variable 2"
4  VARIABLE3: "This is default variable 3"
5
6job1:
7  script: echo "This job does not inherit any default variables."
8  inherit:
9    variables: false
10
11job2:
12  script: echo "This job inherits only the two listed default variables. It does not inherit 'VARIABLE3'."
13  inherit:
14    variables:
15      - VARIABLE1
16      - VARIABLE2

其他详细信息：

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

interruptible#

使用 interruptible 来配置自动取消多余的流水线功能。如果同一 ref 上有新提交触发了流水线，该功能会在作业完成前将其取消。如果禁用，该关键字不起作用。

例如，如果您使用新流水线为同一提交重新运行流水线，该关键字不起作用。

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

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

支持的值：

true 或 false（默认）。

使用默认行为的 interruptible 示例：

yaml
1workflow:
2  auto_cancel:
3    on_new_commit: conservative # the default behavior
4
5stages:
6  - stage1
7  - stage2
8  - stage3
9
10step-1:
11  stage: stage1
12  script:
13    - echo "Can be canceled."
14  interruptible: true
15
16step-2:
17  stage: stage2
18  script:
19    - echo "Can not be canceled."
20
21step-3:
22  stage: stage3
23  script:
24    - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible."
25  interruptible: true

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

如果只有 step-1 正在运行或处于待处理状态，则被取消。
在 step-2 开始后，不被取消。

使用 auto_cancel:on_new_commit:interruptible 设置的 interruptible 示例：

yaml
1workflow:
2  auto_cancel:
3    on_new_commit: interruptible
4
5stages:
6  - stage1
7  - stage2
8  - stage3
9
10step-1:
11  stage: stage1
12  script:
13    - echo "Can be canceled."
14  interruptible: true
15
16step-2:
17  stage: stage2
18  script:
19    - echo "Can not be canceled."
20
21step-3:
22  stage: stage3
23  script:
24    - echo "Can be canceled."
25  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的手动作业，以允许用户手动阻止流水线被自动取消。用户启动作业后，流水线就无法被自动取消多余的流水线功能取消。
将 interruptible 与触发作业一起使用时：
- 被触发的下游流水线永远不会受到触发作业的 interruptible 配置的影响。
- 如果 workflow:auto_cancel 设置为 conservative，则触发作业的 interruptible 配置不起作用。
- 如果 workflow:auto_cancel 设置为 interruptible，则带有 interruptible: true的触发作业可以被自动取消。

needs#

使用 needs 来乱序执行作业。使用 needs的作业之间的关系可以可视化为有向无环图。

您可以忽略阶段顺序，运行某些作业而无需等待其他作业完成。多个阶段中的作业可以并发运行。

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

支持的值：

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

needs 示例：

yaml
1linux:build:
2  stage: build
3  script: echo "Building linux..."
4
5mac:build:
6  stage: build
7  script: echo "Building mac..."
8
9lint:
10  stage: test
11  needs: []
12  script: echo "Linting..."
13
14linux:rspec:
15  stage: test
16  needs: ["linux:build"]
17  script: echo "Running rspec on linux..."
18
19mac:rspec:
20  stage: test
21  needs: ["mac:build"]
22  script: echo "Running rspec on mac..."
23
24production:
25  stage: deploy
26  script: echo "Running production..."
27  environment: production

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

Linter：lint 作业立即运行，无需等待 build 阶段完成，因为它没有 needs（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 数组中可包含的作业数量上限：
- 对于 JihuLab.com，上限为 50。更多信息，请参见议题 350398。
- 对于极狐GitLab 私有化部署，默认上限为 50。可以通过更新管理区域中的 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 示例：

yaml
1test-job1:
2  stage: test
3  needs:
4    - job: build_job1
5      artifacts: true
6
7test-job2:
8  stage: test
9  needs:
10    - job: build_job2
11      artifacts: false
12
13test-job3:
14  needs:
15    - job: build_job1
16      artifacts: true
17    - job: build_job2
18    - build_job3

在此示例中：

test-job1 作业下载 build_job1 产物
test-job2 作业不下载 build_job2 产物。
test-job3 作业下载所有三个 build_jobs的产物，因为对于所有三个所需作业，artifacts 为 true，或默认为 true。

其他详细信息：

您不应在同一作业中同时使用 needs 和 dependencies。

needs:project#

Tier: 专业版，旗舰版

Offering: JihuLab.com，私有化部署

使用 needs:project 从其他流水线中最多五个作业下载产物。产物从指定 ref 的最新成功指定作业下载。要指定多个作业，请将每个作业作为单独的数组项添加到 needs 关键字下。

如果该 ref 有正在运行的流水线，带有 needs:project的作业不会等待该流水线完成。相反，产物会从指定作业的最新成功运行中下载。

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

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

支持的值：

needs:project：完整的项目路径，包括命名空间和群组。
job：要从中下载产物的作业。
ref：要从中下载产物的 ref。
artifacts：必须为 true 才能下载产物。

needs:project 示例：

yaml
1build_job:
2  stage: build
3  script:
4    - ls -lhR
5  needs:
6    - project: namespace/group/project-name
7      job: build-1
8      ref: main
9      artifacts: true
10    - project: namespace/group/project-name-2
11      job: build-2
12      ref: main
13      artifacts: true

在此示例中，build_job 从 group/project-name 和 group/project-name-2 项目中 main 分支上最新成功的 build-1 和 build-2 作业下载产物。

您可以在 needs:project中使用 CI/CD 变量，例如：

yaml
1build_job:
2  stage: build
3  script:
4    - ls -lhR
5  needs:
6    - project: $CI_PROJECT_PATH
7      job: $DEPENDENCY_JOB_NAME
8      ref: $ARTIFACTS_DOWNLOAD_REF
9      artifacts: true

其他详细信息：

要从当前项目中的其他流水线下载产物，请将 project 设置为与当前项目相同，但使用与当前流水线不同的 ref。在同一 ref 上运行的并发流水线可能会覆盖产物。
运行流水线的用户必须对该群组或项目具有报告者、开发者、维护者或所有者角色，或者该群组/项目必须具有公开可见性。
您不能在同一作业中将 needs:project 与 trigger 一起使用。
使用 needs:project 从另一个流水线下载产物时，作业不会等待所需作业完成。使用 needs 等待作业完成仅限于同一流水线中的作业。请确保另一个流水线中的所需作业在需要它的作业尝试下载产物之前完成。
您不能从在 parallel中运行的作业下载产物。
支持在 project、job 和 ref中使用 CI/CD 变量。

相关主题：

要在父子流水线之间下载产物，请使用 needs:pipeline:job。

needs:pipeline:job#

子流水线可以从成功完成的作业下载产物。该作业可以位于其父流水线中，也可以位于同一层级中的另一个子流水线中。

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

支持的值：

needs:pipeline：一个流水线 ID。必须是同一父子流水线层级中存在的流水线。
job：要从中下载产物的作业。
optional：与 needs:optional 一起使用，以依赖有时不存在于父流水线中的作业。

needs:pipeline:job 示例：

父流水线（.gitlab-ci.yml）：

yaml
1stages:
2  - build
3  - test
4
5create-artifact:
6  stage: build
7  script: echo "sample artifact" > artifact.txt
8  artifacts:
9    paths: [artifact.txt]
10
11child-pipeline:
12  stage: test
13  trigger:
14    include: child.yml
15    strategy: mirror
16  variables:
17    PARENT_PIPELINE_ID: $CI_PIPELINE_ID

子流水线（child.yml）：

yaml
use-artifact:
  script: cat artifact.txt
  needs:
    - pipeline: $PARENT_PIPELINE_ID
      job: create-artifact

在此示例中，父流水线中的 create-artifact 作业创建了一些产物。child-pipeline 作业触发了一个子流水线，并将 CI_PIPELINE_ID 变量作为新的 PARENT_PIPELINE_ID 变量传递给子流水线。子流水线可以在 needs:pipeline中使用该变量，从父流水线下载产物。将 create-artifact 和 child-pipeline 作业依次放在前后相继的阶段中，可确保 use-artifact 作业仅在 create-artifact 成功完成后才执行。

其他详细信息：

pipeline 属性不接受当前流水线 ID（$CI_PIPELINE_ID）。要从当前流水线中的作业下载产物，请使用 needs:artifacts。
您不能在触发作业中使用 needs:pipeline:job，也不能从多项目流水线获取产物。要从多项目流水线获取产物，请使用 needs:project。
needs:pipeline:job中列出的作业必须以 success 状态完成，否则无法获取产物。议题 367229 提议允许从任何带有产物的作业获取产物。

needs:optional#

要依赖有时不存在于流水线中的作业，请将 optional: true 添加到 needs 配置中。如果未定义，optional: false 为默认值。您可以将 optional: true 与 needs:pipeline:job 一起使用，以依赖有时不存在于父或另一个子流水线中的作业。

使用 rules、only 或 except 并通过 include 添加的作业可能并不总是被添加到流水线中。极狐GitLab 在启动流水线之前会检查 needs 关系：

如果 needs 条目具有 optional: true 且所需作业存在于流水线中，则作业会等待其完成后再启动。
如果所需作业不存在，则作业可以在满足所有其他 needs 要求时启动。
如果 needs 部分仅包含可选作业，且没有作业被添加到流水线中，则作业立即启动（与空的 needs 条目相同：needs: []）。
如果所需作业具有 optional: false，但它未被添加到流水线中，则流水线无法启动，并出现类似以下错误：'job1' job needs 'job2' job, but it was not added to the pipeline。

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

needs:optional 示例：

yaml
1build-job:
2  stage: build
3
4test-job1:
5  stage: test
6
7test-job2:
8  stage: test
9  rules:
10    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
11
12deploy-job:
13  stage: deploy
14  needs:
15    - job: test-job2
16      optional: true
17    - job: test-job1
18  environment: production
19
20review-job:
21  stage: deploy
22  needs:
23    - job: test-job2
24      optional: true
25  environment: review

在此示例中：

build-job、test-job1 和 test-job2 按阶段顺序启动。
当分支为默认分支时，test-job2 被添加到流水线中，因此：
- deploy-job 等待 test-job1 和 test-job2 都完成。
- review-job 等待 test-job2 完成。
当分支不是默认分支时，test-job2 未被添加到流水线中，因此：
- deploy-job 只等待 test-job1 完成，而不等待缺失的 test-job2。
- review-job 没有其他所需作业，会立即启动（与 build-job 同时），就像 needs: [] 一样。

其他详细信息：

您不能将 needs:optional 与 needs:parallel:matrix 一起使用。

needs:pipeline#

您可以使用 needs:pipeline 关键字将上游流水线的流水线状态镜像到作业。默认分支的最新流水线状态会被复制到该作业。

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

支持的值：

完整的项目路径，包括命名空间和群组。如果项目位于同一群组或命名空间中，您可以从 project 关键字中省略它们。例如：project: group/project-name 或 project: project-name。

needs:pipeline 示例：

yaml
upstream_status:
  stage: test
  needs:
    pipeline: other/project

其他详细信息：

如果您将 job 关键字添加到 needs:pipeline，作业将不再镜像流水线状态。行为会变为 needs:pipeline:job。

needs:parallel:matrix#

作业可以使用 parallel:matrix 在单个流水线中并行多次运行一个作业。作业的每个实例使用不同的变量值。

使用 needs:parallel:matrix 根据并行作业乱序执行作业。

关键字类型：作业关键字。只能作为作业的一部分使用。必须与 needs:job 一起使用。

支持的值：矩阵标识符的哈希数组：

标识符和值必须从 parallel:matrix 作业中定义的标识符和值中选择。
您可以使用矩阵表达式。

needs:parallel:matrix 示例：

yaml
1linux:build:
2  stage: build
3  script: echo "Building linux..."
4  parallel:
5    matrix:
6      - PROVIDER: aws
7        STACK:
8          - monitoring
9          - app1
10          - app2
11
12linux:rspec:
13  stage: test
14  needs:
15    - job: linux:build
16      parallel:
17        matrix:
18          - PROVIDER: aws
19            STACK: app1
20  script: echo "Running rspec on linux..."

上一个示例会生成以下作业：

plaintext
linux:build: [aws, monitoring]
linux:build: [aws, app1]
linux:build: [aws, app2]
linux:rspec

linux:rspec 作业在 linux:build: [aws, app1] 作业完成后立即运行。

其他详细信息：

您不能将 needs:parallel:matrix 与 needs:optional 一起使用。

needs:parallel:matrix中矩阵标识符的顺序必须与所需作业中矩阵变量的顺序一致。例如，颠倒上一个示例中 linux:rspec 作业中变量的顺序将是无效的：

yaml
1linux:rspec:
2  stage: test
3  needs:
4    - job: linux:build
5      parallel:
6        matrix:
7          - STACK: app1        # The variable order does not match `linux:build` and is invalid.
8            PROVIDER: aws
9  script: echo "Running rspec on linux..."

相关主题：

pages#

使用 pages 定义一个 GitLab Pages 作业，将静态内容上传到极狐GitLab。然后该内容会作为网站发布。

您必须：

定义 pages: true 以发布名为 public的目录
或者，如果您想使用不同的内容目录，请定义 pages.publish。
在内容目录的根目录中有一个非空的 index.html 文件。

关键字类型：作业关键字或作业名称（已废弃）。只能作为作业的一部分使用。

支持的值：

布尔值。设置为 true 时使用默认配置
配置选项的哈希，详情请参见以下部分。

pages 示例：

yaml
1create-pages:
2  stage: deploy
3  script:
4    - mv my-html-content public
5  pages: true  # specifies that this is a Pages job and publishes the default public directory
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:  # specifies that this is a Pages job and publishes the default public directory
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 部署，请将 pages 属性设置为 false

pages.publish#

使用 pages.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  # this path is automatically appended to 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  # this path is automatically appended to artifacts:paths
8  rules:
9    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
10  variables:
11    CUSTOM_FOLDER: "custom_folder"
12    CUSTOM_SUBFOLDER: "custom_subfolder"

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

其他详细信息：

顶层 publish 关键字已废弃，现在必须嵌套在 pages 关键字下

pages.path_prefix#

Tier: 专业版，旗舰版

Offering: JihuLab.com，私有化部署

Status: 测试版

使用 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}"
5  pages:  # specifies that this is a Pages job and publishes the default public directory
6    path_prefix: "$CI_COMMIT_BRANCH"

在此示例中，会为每个分支创建不同的 Pages 部署。

pages.expire_in#

Tier: 专业版，旗舰版

Offering: JihuLab.com，私有化部署

使用 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:  # specifies that this is a Pages job and publishes the default public directory
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 数量。多余的作业会排队，并在等待可用 runner 时标记为 pending。
- 如果创建流水线会导致所有活动流水线中的作业总数超过实例限制，则失败并出现 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: [gcp, vultr]
13        STACK: [data, processing]
14  environment: $PROVIDER/$STACK

该示例生成 7 个并行的 deploystacks 作业，每个作业的 PROVIDER 和 STACK 值都不同：

deploystacks: [aws, monitoring]
deploystacks: [aws, app1]
deploystacks: [aws, app2]
deploystacks: [gcp, data]
deploystacks: [gcp, processing]
deploystacks: [vultr, data]
deploystacks: [vultr, processing]

其他详细信息：

parallel:matrix 作业会将矩阵值添加到作业名称中，以区分各个作业。但是，较长的值可能导致作业名称超过 255 个字符的限制。更多信息，请参见史诗 11791。
矩阵变量值可在 rules:if 表达式中作为 CI/CD 变量使用。更多信息，请参见在 rules:if中使用矩阵变量。
您不能创建多个值相同但名称不同的矩阵配置。作业名称是根据矩阵值而非名称生成的，因此值相同的矩阵条目会生成相同的作业名称，从而相互覆盖。

例如，此 test 配置会尝试创建两组相同的作业，但 OS2 版本会覆盖 OS 版本：
```
yaml
1test:
2  parallel:
3    matrix:
4      - OS: [ubuntu]
5        PROVIDER: [aws, gcp]
6      - OS2: [ubuntu]
7        PROVIDER: [aws, gcp]
```

相关主题：

release#

使用 release 创建发布。

发布作业必须能够访问 glab CLI，且该 CLI 必须位于 $PATH中。

如果您使用 Docker 执行器，可以使用来自 GitLab 上游容器镜像仓库的此镜像：registry.gitlab.com/gitlab-org/cli:latest

如果您使用 Shell 执行器或类似执行器，请在注册 runner 的服务器上安装 glab 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/cli:latest
4  rules:
5    - if: $CI_COMMIT_TAG                  # Run this job when a tag is created manually
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 CLI.'

此示例会在以下情况下创建发布：

当您推送 Git 标签时。
当您在 UI 中的代码 > 标签处添加 Git 标签时。

其他详细信息：

发布作业必须包含 script 关键字。发布作业可以使用脚本命令的输出。如果您不需要脚本，可以使用占位符：
```
yaml
script:
  - echo "release job"
```
更多详情，请参见议题 223856，该议题旨在移除此限制。
release 部分在 script 关键字之后、after_script 之前执行。
仅当作业的主脚本成功时才会创建发布。
如果发布已存在，则不会更新，带有 release 关键字的作业会失败。
release 关键字使用 glab CLI，并通过 glab release create 创建发布。默认情况下，发布使用 CI_JOB_TOKEN 进行身份验证。如果在作业中定义了以下任何 CI/CD 变量，glab 会改用该令牌，顺序为：GITLAB_TOKEN、GITLAB_ACCESS_TOKEN 或 OAUTH_TOKEN。在 glab的令牌解析中，这些令牌的优先级高于 CI_JOB_TOKEN。如果此令牌缺少所需的 API 范围，发布可能会失败并出现 401 Unauthorized 错误。

相关主题：

release:tag_name#

必需。发布的 Git 标签。

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

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

支持的值：

标签名称。

支持 CI/CD 变量。

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 由运行 glab的 shell 求值。您可以使用 CI/CD 变量来定义描述，但某些 shell 使用不同的语法来引用变量。同样，某些 shell 可能需要转义特殊字符。例如，反引号（`）可能需要使用反斜杠（\）转义。

release:ref#

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

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

支持的值：

提交 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: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' # optional
8      link_type: 'other' # optional

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 执行器。
- 在极狐GitLab 19.1 中引入，某些失败会从 script_failure 更改为更准确的 runner_configuration_error。
api_failure：在 API 失败时重试。
stuck_or_timeout_failure：当作业卡住或超时时重试。在极狐GitLab 19.1 中已废弃。会在 stuck_pending_with_matching_runners、stuck_pending_no_matching_runners、no_updates_running 或 no_updates_canceling中的任一情况下重试。请改用这些值。在极狐GitLab 19.0 及更高版本中，此原因仅为历史数据保留。新作业会改用下面列出的某个更具体的原因。要在这些情况下重试作业，请同时配置新的原因。
stuck_pending_with_matching_runners：当作业长时间保持待处理状态，即使有匹配的 runner 可用时重试。
stuck_pending_no_matching_runners：当作业因为没有 runner 匹配作业的要求（例如标签或受保护状态）而长时间保持待处理状态时重试。
no_updates_running：当作业处于运行状态但长时间没有活动时重试，例如因为作业脚本挂起或 runner 失去连接。
no_updates_canceling：当作业处于取消中状态但长时间没有活动时重试。
runner_system_failure：如果存在 runner 系统故障（例如作业设置失败）则重试。
- 在极狐GitLab 19.1 中引入，某些失败会从 runner_system_failure 更改为更准确的 runner_external_dependency_failure 或 runner_interrupted。
runner_configuration_error：如果作业因 CI/CD 或 runner 配置错误而失败，例如无效的镜像或标签、不兼容的拉取策略或配置错误的 runner，则重试。
runner_external_dependency_failure：如果 runner 因网络或 DNS 问题无法访问外部依赖（如镜像仓库），则重试。
runner_interrupted：如果 runner 在作业运行期间被中断，例如因重启、关闭或主机回收，则重试。
runner_unsupported：如果 runner 不受支持，则重试。
stale_schedule：如果延迟的作业无法执行，则重试。
job_execution_timeout：如果脚本超过了为作业设置的最大执行时间，则重试。在极狐GitLab 19.1 中已废弃。会在 server_timeout_running 或 server_timeout_canceling中重试。请改用这些值。
server_timeout_running：当正在运行的作业超过其最大执行时间，且服务器端超时强制执行丢弃该作业时重试。
server_timeout_canceling：当正在取消的作业超过其最大执行时间，且服务器端超时强制执行在取消期间丢弃该作业时重试。
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_pending_with_matching_runners
8      - stuck_pending_no_matching_runners
9      - no_updates_running

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 变量的值，但有一些例外。
按照 rules 执行流程的顺序。

作业之间不一致的规则可能导致意外行为，不过 workflow 规则有助于缓解此问题。例如，可能会意外配置出导致重复流水线的作业。

关键字类型：作业特定和流水线特定。您可以将其作为作业的一部分来配置作业行为，或与 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 一起使用。更多详情，请参见议题 327780。
如果某条规则匹配且未定义 when，则该规则使用为作业定义的 when，如果未定义，则默认为 on_success。
您可以在作业级别混用 when 与规则中的 when。 rules中的 when 配置优先于作业级别的 when。
与 script 部分中的变量不同，规则表达式中的变量始终格式化为 $VARIABLE。
- 您可以将 rules:if 与 include 一起使用，以有条件地包含其他配置文件。
=~ 和 !~ 表达式右侧的 CI/CD 变量会作为正则表达式进行评估。

相关主题：

rules:changes#

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

对于新分支流水线，或者没有 Git push 事件时，rules: changes 始终评估为真，作业始终运行。像标签流水线、计划流水线和手动流水线这类流水线都没有关联的 Git push 事件。要覆盖这些情况，请使用 rules: changes: compare_to 指定要与流水线 ref 进行比较的分支。

如果您不使用 compare_to，则应仅将 rules: changes 与分支流水线或合并请求流水线一起使用。不过，创建新分支时 rules: changes 仍会评估为真。具体如下：

合并请求流水线中，rules:changes 将变更与目标合并请求分支进行比较。
分支流水线中，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。
出于性能原因，极狐GitLab 对 changes 模式或文件路径最多执行 50,000 次检查。第 50,000 次检查之后，带模式的 glob 规则始终匹配。换句话说，当变更文件超过 50,000 个，或者变更文件少于 50,000 个但 changes 规则被检查超过 50,000 次时，changes 规则始终假定为匹配。
每个 rules:changes 部分最多可定义 50 个模式或文件路径。
如果任何匹配的文件发生变更，changes 会解析为 true（一种 OR 运算）。
更多示例，请参见使用 rules 指定作业运行时机。
您可以将 $ 字符同时用于变量和路径。例如，如果 $VAR 变量存在，则使用其值。如果不存在，则 $ 会被解释为路径的一部分。
不要使用 ./、双斜杠（//）或任何其他类型的相对路径。路径通过精确字符串比较进行匹配，不会像在 shell 中那样进行评估。

相关主题：

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

rules:changes:paths#

使用 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#

使用 rules:changes:compare_to 指定在比较 rules:changes:paths 下列出的文件变更时，要与哪个 ref 进行比较。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，并且必须与 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 创建的内部提交。
- 在 fork 项目中，请参见议题 424584。

相关主题：

您可以使用 rules:changes:compare_to 来在分支为空时跳过作业。

rules:changes:regexp#

使用 rules:changes:regexp 通过 Ruby 正则表达式（而非 glob 模式）匹配变更的文件路径。

regexp: 和 paths: 互斥。每个 rules:changes 块中只能使用其中一个。

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

支持的值：

一个 Ruby 正则表达式字符串。最大长度为 255 个字符。该模式会与每个变更的文件路径进行匹配。只要至少有一个路径匹配，规则即满足。

支持 CI/CD 变量。模式中的变量会在匹配模式之前展开。255 个字符的限制同样适用于展开后的模式。

rules:changes:regexp 示例：

yaml
1backend-tests:
2  script: rspec
3  rules:
4    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
5      changes:
6        regexp: '\A(?!docs/).*'

在此示例中，当至少有一个变更文件位于 docs/ 目录之外时，backend-tests 会运行。

其他详细信息：

除非您为其添加锚点，否则该模式会匹配路径的任意部分。要匹配完整路径，请使用 \A 和 \z 为模式添加锚点。
请使用 \A 和 \z 而非 ^ 和 $ 为模式添加锚点。Git 允许文件路径中包含换行符，而 ^ 和 $ 会在换行边界处匹配。像 ^(?!docs/) 这样的模式可能匹配到精心构造的包含换行符的路径，例如 docs/ 下的文件后跟一个换行符和另一个路径。
与使用 RE2 的 rules:if 不同，rules:changes:regexp 使用 Ruby 原生正则表达式引擎。
支持前瞻和后顾。
为防止 ReDoS 攻击，该模式受两个超时限制。每个单路径匹配有 50 毫秒的超时，所有路径的评估总预算为 2 秒。如果任一超时被超出，流水线会因配置错误而失败。
如果展开后的模式超过 255 个字符，流水线会因配置错误而失败。
出于性能原因，如果变更文件超过 50,000 个，该规则会评估为 true，而不运行该模式。
您可以将 regexp: 与 compare_to: 组合使用，以控制要与哪个 ref 进行比较。

rules:exists#

使用 exists 在代码仓库中存在特定文件或目录时运行作业。

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

支持的值：

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

rules:exists 示例：

yaml
1job1:
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

在此示例中：

如果代码仓库的根目录中存在 Dockerfile，则运行 job1。
如果代码仓库中任意位置存在 Dockerfile，则运行 job2。

其他详细信息：

Glob 模式使用 Ruby 的 File.fnmatch 进行解释，并带有标志 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB。
出于性能原因，极狐GitLab 对 exists 模式或文件路径最多执行 50,000 次检查。第 50,000 次检查之后，带模式的 glob 规则始终匹配。换句话说，在文件超过 50,000 个的项目中，或者文件少于 50,000 个但 exists 规则被检查超过 50,000 次时，exists 规则始终假定为匹配。
- 如果有多个带模式的 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 部分的项目可能与运行流水线的项目不同：
- 嵌套 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

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

rules:exists:project#

使用 rules:exists:project 指定在何处搜索 rules:exists:paths 下列出的文件。必须与 rules:exists:paths 一起使用。

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

支持的值：

exists:project：完整的项目路径，包括命名空间和群组。
exists:ref：可选。用于搜索文件的提交 ref。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:exists:regexp#

使用 rules:exists:regexp 通过 Ruby 正则表达式（而非 glob 模式）匹配代码仓库中的文件路径。

regexp: 和 paths: 互斥。每个 rules:exists 块中只能使用其中一个。

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

支持的值：

一个 Ruby 正则表达式字符串。最大长度为 255 个字符。该模式会与代码仓库中的每个文件路径进行匹配。只要至少有一个路径匹配，规则即满足。

支持 CI/CD 变量。模式中的变量会在匹配模式之前展开。255 个字符的限制同样适用于展开后的模式。

rules:exists:regexp 示例：

yaml
run-if-go-files-exist:
  script: go test ./...
  rules:
    - exists:
        regexp: '\.go$'

在此示例中，如果代码仓库中任意位置存在任何 .go 文件，则该作业会运行。

其他详细信息：

除非您为其添加锚点，否则该模式会匹配路径的任意部分。要匹配完整路径，请使用 \A 和 \z 为模式添加锚点。
请使用 \A 和 \z 而非 ^ 和 $ 为模式添加锚点。Git 允许文件路径中包含换行符，而 ^ 和 $ 会在换行边界处匹配。像 ^(?!docs/) 这样的模式可能匹配到精心构造的包含换行符的路径，例如 docs/ 下的文件后跟一个换行符和另一个路径。
与使用 RE2 的 rules:if 不同，rules:exists:regexp 使用 Ruby 原生正则表达式引擎。
支持前瞻和后顾。
为防止 ReDoS 攻击，该模式受两个超时限制。每个单路径匹配有 50 毫秒的超时，所有路径的评估总预算为 2 秒。如果任一超时被超出，流水线会因配置错误而失败。
如果展开后的模式超过 255 个字符，流水线会因配置错误而失败。
出于性能原因，如果代码仓库包含超过 50,000 个文件，该规则会评估为 true，而不运行该模式。
您可以将 regexp: 与 project: 和 ref: 组合使用，以在其他项目中搜索。

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#

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

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

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

支持的值：

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。

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

支持的值：

一个由作业名称字符串组成的数组。
一个包含作业名称的哈希，可选地带有其他属性。
一个空数组（[]），用于在满足特定条件时将作业的 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 可以接受 artifacts 和 optional。

rules:variables#

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

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

支持的值：

一个变量哈希，格式为 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#

Status: 实验

此功能可用于测试，但尚未准备好用于生产环境。

使用 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、after_script 或 before_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#

Tier: 专业版，旗舰版

Offering: JihuLab.com，私有化部署

使用 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:  # Store the path to the secret in this CI/CD variable
4      vault:  # Translates to secret: `ops/data/production/db`, field: `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:  # Store the path to the secret in this CI/CD variable
      vault: production/db/password  # Translates to secret: `kv-v2/data/production/db`, field: `password`

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

yaml
job:
  secrets:
    DATABASE_PASSWORD:  # Store the path to the secret in this CI/CD variable
      vault: production/db/password@ops  # Translates to secret: `ops/data/production/db`, field: `password`

secrets:gcp_secret_manager#

使用 secrets:gcp_secret_manager 指定由 GCP 密钥管理器提供的密钥。

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

支持的值：

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 密钥管理器密钥。

secrets:gitlab_secrets_manager#

使用 secrets:gitlab_secrets_manager 指定来自极狐GitLab 密钥管理器的密钥。

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

支持的值：

name：密钥的名称。
source：可选。密钥的来源。未指定时默认为当前项目。对于群组密钥，请使用 group/<full-path-to-group>。

secrets:gitlab_secrets_manager 示例：

yaml
job:
  secrets:
    MY_DEPLOY_SECRET:
      gitlab_secrets_manager:
        name: deployment_token

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:services，而作业也定义了 services，则作业配置优先，不使用默认配置。

要启用服务间网络，请将 FF_NETWORK_PER_BUILD 设置为 true。如果没有此功能标志，服务可能无法正常工作。更多信息，请参见功能标志

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：服务镜像的名称，包括所需的仓库路径，采用以下格式之一：

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

支持 CI/CD 变量，但不支持用于 alias。要动态自定义 alias，请改用 CI/CD 输入。

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 命令可以连接到主机名为 db-postgres的 PostgreSQL 数据库。

其他详细信息：

在顶层使用 services（而不是在 default 部分中）已被弃用。

相关主题：

services:name#

用于该服务的镜像的完整名称。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：服务镜像的名称，包括所需的仓库路径，采用以下格式之一：

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

支持 CI/CD 变量。

services:name 示例：

yaml
services:
  - name: postgres:11.7
  - name: registry.example.com/my-org/custom-service:latest

其他详细信息：

在使用多个相同的服务镜像，或服务镜像名称较长时，使用 alias 定义唯一的名称别名。
当与 entrypoint、command 或 variables 等其他服务选项一起使用时，name 关键字是必需的。
更多信息，请参见访问服务。

services:alias#

用于从作业容器访问服务的其他别名。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：一个字符串，包含一个或多个以空格或逗号分隔的别名。

services:alias 示例：

yaml
services:
  - name: postgres:11.7
    alias: db,postgres,pg
  - name: mysql:latest
    alias: mysql-1

其他详细信息：

多个别名可以用空格或逗号分隔。
更多信息，请参见访问服务以及将别名用作 Kubernetes 执行器的服务容器名称。

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 选项。
使用 Docker 执行器时，要运行针对与 runner 主机不同架构构建的服务镜像，主机必须注册有 binfmt_misc的模拟支持。更多信息，请参见 image:docker。

services:kubernetes#

使用 services:kubernetes 将选项传递给极狐GitLab Runner Kubernetes 执行器。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

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

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

仅包含 UID 的 services:kubernetes 示例：

yaml
1arm-sql-job:
2  script: echo "Run sql tests"
3  image: ruby:2.6
4  services:
5    - name: super/sql:experimental
6      kubernetes:
7        user: "1001"

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

yaml
1arm-sql-job:
2  script: echo "Run sql tests"
3  image: ruby:2.6
4  services:
5    - name: super/sql:experimental
6      kubernetes:
7        user: "1001:1001"

services:entrypoint#

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

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

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：一个表示入口点命令的字符串数组。

services:entrypoint 示例：

yaml
services:
  - name: my-postgres:11.7
    entrypoint: ["/usr/local/bin/db-postgres"]

services:command#

应用作容器命令的命令或脚本。

它会转换为在镜像名称之后传递给 Docker 的参数。语法类似于 Dockerfile CMD 指令，其中每个 shell 令牌都是数组中的一个单独字符串。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：一个表示命令的字符串数组。

services:command 示例：

yaml
services:
  - name: super/sql:latest
    command: ["/usr/bin/super-sql", "run"]

services:variables#

仅传递给该服务的其他环境变量。服务变量仅传递给服务容器，作业容器无法使用。

语法与作业变量相同。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：一个环境变量名称和值的哈希。

services:variables 示例：

yaml
1services:
2  - name: postgres:11.7
3    alias: db
4    variables:
5      POSTGRES_DB: "my_custom_db"
6      POSTGRES_USER: "postgres"
7      POSTGRES_PASSWORD: "example"
8      PGDATA: "/var/lib/postgresql/data"

其他详细信息：

服务变量不能引用自身，它们不支持变量展开或插值。
在作业或流水线级别定义的变量会自动传递给服务。更多信息，请参见将 CI/CD 变量传递给服务。
服务变量仅对为其定义的特定服务可用。

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

相关主题：

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: [] 的作业会立即启动，忽略任何阶段配置。
流水线执行策略可以定义在 .pre 之前运行的 .pipeline-policy-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."

其他详细信息：

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

tags#

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

作业配置和默认配置不会合并在一起。如果流水线定义了 default:tags，而作业也定义了 tags，则作业配置优先，不使用默认配置。

关键字类型：作业关键字。您只能将其作为作业的一部分使用，或在 default 部分中使用。

支持的值：

一个标签名称数组，区分大小写。
支持 CI/CD 变量。

tags 示例：

yaml
job:
  tags:
    - ruby
    - postgres

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

其他详细信息：

标签数量必须少于 50。

相关主题：

timeout#

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

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

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

支持的值：用自然语言表示的一段时间。例如，以下写法都等效：

3600 seconds
60 minutes
one hour

timeout 示例：

yaml
1build:
2  script: build.sh
3  timeout: 3 hours 30 minutes
4
5test:
6  script: rspec
7  timeout: 3h 30m

其他详细信息：

default 配置中不支持 timeout 关键字。请改为在各个作业配置中定义 timeout。更多信息，请参见议题 213634。

trigger#

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

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

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

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

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

支持的值：

对于多项目流水线，为下游项目的路径。支持 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#

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

trigger:inputs 示例：

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

trigger:include#

使用 trigger:include 声明某个作业是“触发作业”，它会启动子流水线。

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

支持的值：

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

路径中对 CI/CD 变量的支持有限，请参见 trigger:include 路径中的变量为空或值不符合预期。请考虑改用输入。

trigger:include 示例：

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

其他详细信息：

使用：

trigger:include:artifact 触发动态子流水线。
trigger:include:inputs 在下游流水线配置使用 spec:inputs 时设置输入。
trigger:include:local 用于在以下情况下指定子流水线配置文件的路径：
- 组合多个子流水线配置文件。
- 与 trigger:include:inputs 组合使用，以将输入传递给子流水线。例如：
```
yaml
1staging-job:
2  trigger:
3    include:
4      - local: path/to/child-pipeline.yml
5        inputs:
6          environment: staging
```
trigger:include:project 触发使用其他项目中的配置文件的子流水线。如果该文件包含其他 include 条目，极狐GitLab 会在运行流水线的项目中查找这些文件，而不是在托管该文件的项目中查找。
trigger:include:template 使用 CI/CD 模板触发子流水线。

相关主题：

子流水线配置示例。

trigger:include:inputs#

当下游流水线配置使用 spec:inputs 时，使用 trigger:include: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 变量，但不支持仅作业变量。

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 作业会在下游流水线创建后立即被标记为成功。

此设置会使您的流水线执行变为线性而非并行。

支持的值：

mirror：完全镜像下游流水线的状态。
depend：不推荐，请改用 mirror。触发作业状态会显示已失败、成功或运行中，具体取决于下游流水线的状态。请参见其他详细信息。

trigger:strategy 示例：

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

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

其他详细信息：

下游流水线中的可选手动作业不会影响下游流水线或上游触发作业的状态。下游流水线可以在不运行任何可选手动作业的情况下成功完成。
默认情况下，后续阶段中的作业要等到触发作业完成后才会开始。
下游流水线中的阻塞手动作业必须先运行，触发作业才会被标记为成功或失败。
使用 strategy:depend 时（不再推荐，请改用 strategy:mirror）：
- 如果下游流水线状态为 等待手动操作（），则触发作业会显示运行中（）。
- 如果下游流水线有失败的作业，但该作业使用了 allow_failure: true，则下游流水线被视为成功，触发作业会显示成功。

trigger:forward#

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

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

支持的值：

yaml_variables：true（默认）或 false。当为 true 时，触发作业中定义的变量会传递到下游流水线。这包括作业继承的默认变量，以及直接在触发作业的 variables 块中定义的变量。
pipeline_variables：true 或 false（默认）。当为 true 时，流水线变量会传递到下游流水线。这包括来自手动流水线运行、计划流水线的变量，以及 needs中列出的作业的 dotenv 变量。

trigger:forward 示例：

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

yaml
1variables: # default variables for each job
2  VAR: value
3
4---
5
6# Default behavior:
7---
8
9# - VAR is passed to the child
10---
11
12# - MYVAR is not passed to the child
13child1:
14  trigger:
15    include: .child-pipeline.yml
16
17---
18
19# Forward pipeline variables:
20---
21
22# - VAR is passed to the child
23---
24
25# - MYVAR is passed to the child
26child2:
27  trigger:
28    include: .child-pipeline.yml
29    forward:
30      pipeline_variables: true
31
32---
33
34# Do not forward YAML variables:
35---
36
37# - VAR is not passed to the child
38---
39
40# - MYVAR is not passed to the child
41child3:
42  trigger:
43    include: .child-pipeline.yml
44    forward:
45      yaml_variables: false

其他详细信息：

使用 trigger:forward 转发到下游流水线的 CI/CD 变量是流水线变量，具有较高的优先级。如果下游流水线中定义了同名的变量，该变量通常会被转发的变量覆盖。
forward:yaml_variables 也会影响 trigger:include 路径中的 CI/CD 变量。更多信息，请参见 trigger:include 路径中的变量为空或值不符合预期。

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

在此示例中，脚本：

仅当 build_job 失败时才执行 cleanup_build_job。
无论成功还是失败，始终将 cleanup_job 作为流水线中的最后一步执行。
当您在极狐GitLab UI 中手动运行 deploy_job 时执行该作业。

其他详细信息：

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

相关主题：

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

manual_confirmation#

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

手动确认适用于所有手动作业，包括使用 environment:action: stop的环境停止作业。

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

支持的值：

包含确认消息的字符串。

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?'
7
8stop_production:
9  stage: cleanup
10  script:
11    - echo "Stopping production environment"
12  environment:
13    name: production
14    action: stop
15  when: manual
16  manual_confirmation: "Are you sure you want to stop the production environment?"

start_in#

使用 start_in 在作业创建后延迟指定时长再执行该作业。您必须为该作业配置 when: delayed。

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

可能的输入：以秒、分钟或小时为单位的时间段。必须小于或等于一周。有效值示例：

'5'（5 秒）
'10 seconds'
'30 minutes'
'1 hour'
'1 day'

start_in 示例：

yaml
1deploy_production:
2  stage: deploy
3  script:
4    - echo "Deploying to production"
5  when: delayed
6  start_in: 30 minutes

在此示例中，deploy_production 作业在前一阶段完成 30 分钟后启动。

其他详细信息：

计时器在作业所在阶段开始时启动，而不是在前一个作业完成时启动。
要立即手动启动延迟作业，请在流水线视图中选择运行（）。
最短延迟时间为一秒，最长延迟时间为一周。
start_in 仅在 when 设置为 delayed 时才有效。如果您为 when 使用任何其他值，该配置无效。如果作业使用 rules，则 start_in 和 when 必须在 rules中定义，而不是在作业级别定义。否则，您会收到验证错误：config key may not be used with 'rules': start_in。
start_in 不支持与 workflow:rules 一起使用，但不会导致任何语法违规。

相关主题：

延迟后运行作业

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 一起使用。