.gitlab-ci.yml 关键字参考

本文档列出了 GitLab .gitlab-ci.yml 文件的配置选项。

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

关键字

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

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

全局关键字

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

default

您可以为某些关键字设置全局默认值。 未定义一个或多个所列关键字的作业使用在 default: 部分中定义的值。

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

可能的输入：以下关键字可以具有自定义默认值： 

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: ruby:2.7
  script: bundle exec rspec

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

额外细节：

  • 创建流水线时，每个默认值都会复制到所有未定义该关键字的作业。
  • 如果作业已经配置了其中一个关键字，则作业中的配置优先，不会被默认替换。
  • 使用 inherit:default 控制作业中默认关键字的继承。

stages

使用 stages 来定义包含作业组的阶段。stages 是为流水线全局定义的。在作业中使用 stage 来定义作业属于哪个阶段。

如果 .gitlab-ci.yml 文件中没有定义 stages，那么默认的流水线阶段是：

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

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

例如： 

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

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

如果作业未指定 stage，则作业被分配到 test 阶段。

如果定义了一个阶段，但没有作业使用它，则该阶段在流水线中不可见。 这对合规流水线配置很有用，因为：

  • 阶段可以在合规性配置中定义，但如果不使用则保持隐藏。
  • 当开发人员在作业定义中使用它们时，定义的阶段变得可见。

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

workflow

使用 workflow: 来确定是否创建流水线。 在顶层定义此关键字，使用单个 rules: 关键字，类似于在作业中定义的 rules:。

workflow:name

  • 引入于 15.5 版本，功能标志为 pipeline_name。默认禁用。
  • 在 SaaS 版和私有化部署版上启用于 15.7 版本。
  • 一般可用于 15.8 版本。功能标志 pipeline_name 已删除。

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

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

可能的输入：

workflow:name 示例： 

workflow:
  name: 'Pipeline name'

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

variables:
  PROJECT1_PIPELINE_NAME: 'Default pipeline name'  # A default is not required.

workflow:
  name: '$PROJECT1_PIPELINE_NAME'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PROJECT1_PIPELINE_NAME: 'MR pipeline: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
    - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/'
      variables:
        PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline'

额外细节：

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

workflow:rules

您可以使用 workflow:rules 模板 导入预先配置的 workflow:rules 条目。

workflow: rules 接受这些关键字：

  • if：检查此规则以确定何时运行流水线。
  • when：指定当 if 规则为 true 时要做什么。
    • 要运行流水线，请设置为 always。
    • 要阻止流水线运行，请设置为 never。
  • variables：如果未定义，则使用在别处定义的变量。

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

workflow: rules 的一些示例 if 子句如下：

示例规则 详细信息
if: '$CI_PIPELINE_SOURCE == "merge_request_event"' 控制合并请求流水线何时运行。
if: '$CI_PIPELINE_SOURCE == "push"' 控制分支流水线和标签流水线何时运行。
if: $CI_COMMIT_TAG 控制标签流水线何时运行。
if: $CI_COMMIT_BRANCH 控制分支流水线何时运行。

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

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  • 合并请求
  • 默认分支

这个例子有严格的规则，流水线在任何其他情况下都不运行。

或者，所有规则都可以是 when: never，最后是 when:always 规则。匹配 when: never 规则的流水线不会运行。 所有其他流水线类型运行： 

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "push"'
      when: never
    - when: always

此示例阻止了计划或 push（分支和标签）的流水线。 最后的 when: always 规则运行所有其他流水线类型，包括合并请求流水线。

如果您的规则同时匹配分支流水线和合并请求流水线，则可能会出现重复流水线。

workflow:rules:variables

  • 引入于 13.11 版本
  • 功能标志移除于 14.1 版本。

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

当条件匹配时，将创建该变量并可供流水线中的所有作业使用。如果该变量已在全局级别定义，则 workflow 变量优先并覆盖全局变量。

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

可能的输入：变量名和值对：

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

workflow:rules:variables 示例： 

variables:
  DEPLOY_VARIABLE: "default-deploy"

workflow:
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:
        DEPLOY_VARIABLE: "deploy-production"  # Override globally-defined DEPLOY_VARIABLE
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Define a new variable.
    - when: always                            # Run the pipeline in other cases

job1:
  variables:
    DEPLOY_VARIABLE: "job1-default-deploy"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:                                   # Override DEPLOY_VARIABLE defined
        DEPLOY_VARIABLE: "job1-deploy-production"  # at the job level.
    - when: on_success                             # Run the job in other cases
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

job2:
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - 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 并列出要转发到下游流水线的确切变量。

include

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

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

include 文件：

  • 与 .gitlab-ci.yml 文件中的那些合并。
  • 无论 include 关键字的位置如何，始终先求值，然后与 .gitlab-ci.yml 文件的内容合并。

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

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

可能的输入：include 子键：

额外细节：

  • 使用合并来自定义和覆盖本地包含的 CI/CD 配置。
  • 您可以通过在 .gitlab-ci.yml 文件中使用相同的作业名称或全局关键字，来覆盖包含的配置。这两个配置合并在一起，.gitlab-ci.yml 文件中的配置优先于包含的配置。
  • 如果您重新运行：
    • 作业，include 文件不会再次获取。流水线中的所有作业都使用创建流水线时获取的配置。对源 include 文件的任何更改都不会影响作业重新运行。
    • 流水线，include 文件被再次获取。如果它们在上次流水线运行后发生更改，则新流水线将使用更改后的配置。

include:local

使用 include:local 包含与带有 include 关键字的配置文件位于同一仓库中的文件。 使用 include:local 代替符号链接。

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

可能的输入：

相对于根目录 (/) 的完整路径：

include:local 示例： 

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

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

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

额外细节：

  • .gitlab-ci.yml 文件和本地文件必须在同一个分支上。
  • 您不能通过 Git 子模块路径包含本地文件。
  • 所有的 nested includes 都在同一个项目范围内执行，所以您可以使用本地、项目、远端或模板 include。

include:project

包含来自同一项目的多个文件引入于 13.6 版本。功能标志移除于 13.8 版本。

要在同一个实例上包含来自另一个私有项目的文件，使用 include:project 和 include:file。

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

可能的输入：

  • include:project：完整的极狐GitLab 项目路径。
  • include:file：相对于根目录（/）的完整文件路径或文件路径数组。YAML 文件必须具有 .yml 或 .yaml 扩展名。
  • include:ref：可选。从中检索文件的 ref。未指定时默认为项目的 HEAD。

include:project 示例： 

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

您还可以指定一个 ref。 

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

额外细节：

  • 所有 nested includes 都在包含带有嵌套 include 关键字的配置文件的项目的范围内执行。您可以使用 local（相对于包含带有 include 关键字的配置文件的项目）、project、remote 或 template include。
  • 当流水线启动时，评估所有方法 include 的 .gitlab-ci.yml 文件配置。配置是一个及时的快照并持久存在于数据库中。在下一个流水线启动之前，系统不会反映对引用的 .gitlab-ci.yml 文件配置的任何更改。
  • 当您包含来自另一个私有项目的 YAML 文件时，运行流水线的用户必须是这两个项目的成员并且具有运行流水线的适当权限。如果用户无权访问任何包含的文件，则可能会显示 not found or access denied 错误。

include:remote

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

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

可能的输入：可通过 HTTP/HTTPS GET 请求访问的公共 URL。不支持使用远端 URL 进行身份验证。

YAML 文件的扩展名必须是 .yml 或 .yaml。

include:remote 示例： 

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

额外细节：

  • 所有 nested includes 都以公共用户身份在没有上下文的情况下执行，因此您只能包含公共项目或模板。
  • 包含远端 CI/CD 配置文件时要小心。当外部 CI/CD 配置文件更改时，不会触发任何流水线或通知。从安全角度来看，这类似于拉取第三方依赖项。

include:template

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

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

可能的输入：.gitlab-ci.yml 模板.

include:template 示例： 

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

多个 include:template 文件： 

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

额外细节：

  • 所有 nested includes 仅在用户许可的情况下执行，因此可以使用 project、remote 或 template include。

作业关键字

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

hooks

  • 引入于 15.6 版本，功能标志为 ci_hooks_pre_get_sources_script。默认禁用。
  • 一般可用于 15.10 版本。功能标志 ci_hooks_pre_get_sources_script 已删除。

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

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

可能的输入：

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

hooks:pre_get_sources_script

  • 引入于 15.6 版本，功能标志为 ci_hooks_pre_get_sources_script。默认禁用。
  • 一般可用于 15.10 版本。功能标志 ci_hooks_pre_get_sources_script 已删除。

在检索 Git 代码库和任何 submodules 之前，使用 hooks:pre_get_sources_script 指定要在 runner 上执行的命令列表。例如，您可以先使用它来调整 Git 客户端配置。

hooks:pre_get_sources_script 示例： 

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

id_tokens

引入于 15.7 版本。

使用 id_tokens 创建 JSON 网络令牌（JWT）通过第三方服务进行身份验证。所有以这种方式创建的 JWT 都支持 OIDC 身份验证。所需的 aud 子关键字用于配置 JWT 的 aud 声明。

可能的输入：

  • 带有 aud 声明的令牌名称。aud 可以是单个字符串或字符串数组。

id_tokens 示例： 

job_with_id_tokens:
  id_tokens:
    ID_TOKEN_1:
      aud: https://gitlab.com
    ID_TOKEN_2:
      aud:
        - https://gcp.com
        - https://aws.com
  script:
    - command_to_authenticate_with_gitlab $ID_TOKEN_1
    - command_to_authenticate_with_aws $ID_TOKEN_2

image

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

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

可能的输入：镜像的名称，包括镜像库路径（如果需要），采用以下格式之一：

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

image 示例： 

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

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

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

image:name

作业运行所在的 Docker 镜像的名称。与自身使用的 image: 类似。

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

可能的输入：镜像的名称，包括镜像库路径（如果需要），采用以下格式之一：

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

image:name 示例： 

image:
  name: "registry.example.com/my/image:latest"

image:pull_policy

  • 引入于 15.1 版本，功能标志为 ci_docker_image_pull_policy。默认禁用。
  • 需要极狐GitLab Runner 15.1 或更高版本。

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

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

可能的输入：

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

image:pull_policy 示例： 

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

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

额外细节：

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

image:entrypoint

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

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

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

可能的输入：一个字符串。

image:entrypoint 示例： 

image:
  name: super/sql:experimental
  entrypoint: [""]

services

使用 services 指定您的脚步成功运行所需的任何其他 Docker 镜像。services 镜像链接到 image 关键字中指定的镜像。

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

可能的输入：服务镜像的名称，包括镜像库路径（如果需要），采用以下格式之一：

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

services 示例： 

default:
  image:
    name: ruby:2.6
    entrypoint: ["/bin/bash"]

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

  before_script:
    - bundle install

test:
  script:
    - bundle exec rake spec

在此示例中，作业启动一个 Ruby 容器。然后，该作业从该容器启动另一个运行 PostgreSQL 的容器。然后该作业在该容器中运行脚本。

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

  • 运行 script 命令的 Ruby 容器。
  • 一个 PostgreSQL 容器。Ruby 容器中的 script 命令可以连接到位于 db-postgrest 主机名的 PostgreSQL 数据库。

service:pull_policy

  • 引入于 15.1 版本，功能标志为 ci_docker_image_pull_policy。默认禁用。
  • 在 SaaS 版和私有化部署版上启用于 15.2 版本。
  • 需要极狐GitLab Runner 15.1 或更高版本。

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

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

可能的输入：

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

service:pull_policy 的示例： 

job1:
  script: echo "A single pull policy."
  services:
    - name: postgres:11.6
      pull_policy: if-not-present

job2:
  script: echo "Multiple pull policies."
  services:
    - name: postgres:11.6
      pull_policy: [always, if-not-present]

额外细节：

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

script

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

除了 trigger jobs 之外的所有作业都需要一个 script 关键字。

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

可能的输入：一个数组，包括：

script 示例： 

job1:
  script: "bundle exec rspec"

job2:
  script:
    - uname -a
    - bundle exec rspec

额外细节：

before_script

使用 before_script 来定义一系列命令，这些命令应该在每个作业的 script 命令之前运行，但在 artifacts 恢复之后。

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

可能的输入：一个数组，包括：

before_script 示例： 

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

额外细节：

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

after_script

使用 after_script 定义在每个作业之后运行的命令数组，包括失败的作业。

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

可能的输入：一个数组，包括：

Example of after_script: 

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

额外细节：

您在 after_script 中指定的脚本在一个新的 shell 中执行，与任何 before_script 或 script 命令分开。结果：

  • 将当前工作目录设置回默认值（根据定义运行程序如何处理 Git 请求的变量）。
  • 无权访问由 before_script 或 script 中定义的命令完成的更改，包括：
    • 在script 脚本中导出的命令别名和变量。
    • 作业树之外的更改（取决于 runner），例如由 before_script 或 script 脚本安装的软件。
  • 有一个单独的超时，它被硬编码为 5 分钟。
  • 不要影响作业的退出代码。如果 script 部分成功并且 after_script 超时或失败，作业将退出，代码为 0（Job Succeeded）。

如果作业超时或被取消，则不会执行 after_script 命令。 存在一个问题，即为超时或取消的作业添加对执行 after_script 命令的支持。

stage

使用 stage 定义作业在哪个 stage 中运行。同一个 stage 中的作业可以并行执行（参见 额外细节）。

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

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

可能的输入：包含任意数量阶段名称的数组。 阶段名称可以是：

stage 示例： 

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - echo "This job compiles code."

job2:
  stage: test
  script:
    - echo "This job tests the compiled code. It runs when the build stage completes."

job3:
  script:
    - echo "This job also runs in the test stage".

job4:
  stage: deploy
  script:
    - echo "This job deploys the code. It runs when the test stage completes."
  environment: production

额外细节：

  • 如果作业在不同的 runner 上运行，则它们可以并行运行。
  • 如果您只有一个 runner，如果 runner 的 concurrent 设置大于 1，作业可以并行运行。

stage: .pre

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

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

关键字类型：您只能将它与作业的 stage 关键字一起使用。

stage: .pre 示例： 

stages:
  - build
  - test

job1:
  stage: build
  script:
    - echo "This job runs in the build stage."

first-job:
  stage: .pre
  script:
    - echo "This job runs in the .pre stage, before all other stages."

job2:
  stage: test
  script:
    - echo "This job runs in the test stage."

stage: .post

使用 .post 阶段使作业在流水线的末尾运行。.post 始终是流水线的最后阶段。用户定义的阶段在 .post 之前执行。 你不必在 stages 中定义 .post。

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

关键字类型：您只能将它与作业的 stage 关键字一起使用。

stage: .post 示例： 

stages:
  - build
  - test

job1:
  stage: build
  script:
    - echo "This job runs in the build stage."

last-job:
  stage: .post
  script:
    - echo "This job runs in the .post stage, after all other stages."

job2:
  stage: test
  script:
    - echo "This job runs in the test stage."

额外细节：

  • 如果流水线有包含 needs: [] 的作业和 .pre 阶段的作业，它们将在流水线创建后立即启动。具有 needs: [] 的作业会立即启动，忽略任何阶段配置。

extends

使用 extends 来重用配置 section。它是 YAML 锚点 的替代方案，并且更加灵活和可读。

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

可能的输入：

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

extends 示例： 

.tests:
  script: rake test
  stage: test
  only:
    refs:
      - branches

rspec:
  extends: .tests
  script: rake rspec
  only:
    variables:
      - $RSPEC

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

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

结果是这个 rspec 作业： 

rspec:
  script: rake rspec
  stage: test
  only:
    refs:
      - branches
    variables:
      - $RSPEC

额外示例：

  • 在 12.0 及更高版本中，您可以为 extends 使用多个父项。
  • extends 关键字最多支持 11 级继承，但应避免使用超过 3 级。
  • 在上面的例子中，.tests 是一个隐藏作业，但也可以从常规作业扩展配置。

rules

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

创建流水线时会评估规则，并按顺序评估，直到第一次匹配。找到匹配项后，该作业将包含在流水线中或从流水线中排除，具体取决于配置。

您不能在规则中使用作业脚本中创建的 dotenv 变量，因为在任何作业运行之前都会评估规则。

rules 替换了 only/except，并且它们不能在同一个作业中一起使用。如果您将一个作业配置为使用两个关键字，则系统会返回一个 key may not used with rules 错误。

rules 接受以下规则：

  • if
  • changes
  • exists
  • allow_failure
  • variables
  • when

您可以为复杂规则，将多个关键字组合在一起。

作业被添加到流水线中：

  • 如果 if、changes 或 exists 规则匹配并且还具有 when: on_success（默认）、when: delay 或 when: always。
  • 如果达到的规则只有 when: on_success、when: delay 或 when: always。

作业未添加到流水线中：

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

您可以在不同的工作中使用 !reference 标签 来重用 rules 配置。

rules:if

使用 rules:if 子句指定何时向流水线添加作业：

  • 如果 if 语句为 true，则将作业添加到流水线中。
  • 如果 if 语句为 true，但它与 when: never 结合使用，则不要将作业添加到流水线中。
  • 如果没有 if 语句为 true，则不要将作业添加到流水线中。

if: 子句根据预定义 CI/CD 变量或自定义 CI/CD 变量。

关键字类型：特定于作业和特定于流水线。您可以将其用作作业的一部分来配置作业行为，或者使用 workflow 来配置流水线行为。

可能的输入：CI/CD 变量表达式。

rules:if 示例： 

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH
      when: never
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/
      when: manual
      allow_failure: true
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME

额外细节：

  • 如果规则匹配并且没有定义 when，则规则使用为作业定义的 when，如果未定义，则默认为 on_success。
  • 在 14.5 及更早版本中，您可以为每个规则定义一次 when，或者在适用于所有规则的作业级别定义一次。 您不能将作业级别的 when 与规则中的 when 混用。
  • 在 14.6 及更高版本中，您可以将作业级别的 when 与规则中的 when 混合使用。rules 中的 when 配置优先于在作业级别的 when。
  • 与 script 部分中的变量不同，规则表达式中的变量始终格式为 $VARIABLE。
    • 您可以使用 rules:if 和 include 来有条件地包含其他配置文件。
  • =~ 和 !~ 表达式右侧的变量被认为是正则表达式。

rules:changes

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

caution您应该仅将 rules: changes 用于 分支流水线 或 合并请求流水线。 您可以将 rules:changes 与其他管道类型一起使用，但是当没有 Git push 事件时，rules:changes 总是评估为 true。 标记流水线、计划流水线和手动流水线等没有与它们关联的 Git push 事件。 如果没有将作业限制为分支或合并请求管道的 if:，则 rules: changes 作业总是 添加到这些管道中。

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

可能的输入：

一个包含任意数量的数组：

  • 文件的路径。在 13.6 及更高版本中，文件路径可以包含变量。文件路径数组也可以在 rules:changes:paths 中。
  • 通配符路径：
    • 单个目录，例如 path/to/directory/*。
    • 目录及其所有子目录，例如 path/to/directory/**/*。
  • 具有相同扩展名或多个扩展名的所有文件的通配符全局路径，例如 *.md 或 path/to/directory/*.{rb,py,sh}。有关支持的语法列表，请参阅 Ruby fnmatch 文档。
  • 根目录或所有目录中文件的通配符路径，用双引号括起来。 例如 "*.json" 或 "**/*.json"。

rules:changes 示例： 

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - Dockerfile
      when: manual
      allow_failure: true
  • 如果流水线是合并请求流水线，请检查 Dockerfile 是否有更改。
  • 如果 Dockerfile 已更改，则将作业作为手动作业添加到流水线中，即使作业未触发，流水线也会继续运行（allow_failure: true）。
  • 如果 Dockerfile 没有改变，不要将作业添加到任何流水线（与 when: never 相同）。
  • rules:changes:paths 与 rules:changes 相同，没有任何子键。

额外细节：

  • rules: changes 的工作方式与 only: changes 和 except: changes 相同。
  • 您可以使用 when: never 来实现类似于 except:changes 的规则。
  • 如果任何匹配的文件发生更改（OR 操作），changes 将解析为 true。
rules:changes:paths

引入于 15.2 版本。

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

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

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

可能的输入：

  • 文件路径数组。在 13.6 及更高版本中，文件路径可以包含变量。

rules:changes:paths 示例： 

docker-build-1:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile

docker-build-2:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile

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

rules:changes:compare_to
  • 引入于 15.3 版本，功能标志为 ci_rules_changes_compare。默认启用。
  • 一般可用于 15.5 版本。功能标志 ci_rules_changes_compare 已删除。

使用 rules:changes:compare_to 指定要比较哪个 ref 来比较 rules:changes:paths 下列出的文件的更改。

关键字类型：作业关键字。您只能将其用作作业的一部分，并且必须与 rules:changes:paths 结合使用。

可能的输入：

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

rules:changes:compare_to 示例： 

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile
        compare_to: 'refs/heads/branch1'

在此示例中，仅当 Dockerfile 相对于 refs/heads/branch1 发生更改并且流水线源是合并请求事件时，才包含 docker build 作业。

rules:exists

  • 引入于 12.4 版本。
  • CI/CD 变量支持引入于 15.6 版本。

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

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

可能的输入：文件路径数组。路径相对于项目目录 ($CI_PROJECT_DIR)，不能直接链接到项目目录之外。文件路径可以使用 glob 样式和 CI/CD 变量。

rules:exists 示例： 

job:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        - Dockerfile

job runs if a Dockerfile exists anywhere in the repository.

额外细节：

  • Glob 模式使用 Ruby File.fnmatch 和标志 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB。
  • 出于性能原因，系统最多匹配 10,000 个 exists pattern 或文件路径。在第 10,000 次检查之后，有 patterned globs的规则始终匹配。也就是说，exists 规则总是假设在超过 10,000 个文件的项目中匹配。
  • 如果找到任何列出的文件，exists 解析为 true（OR 操作）。

rules:allow_failure

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

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

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

可能的输入：true 或 false。如果未定义，则默认为 false。

rules:allow_failure 示例： 

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
      when: manual
      allow_failure: true

如果规则匹配，则该作业是带有 allow_failure: true 的手动作业。

额外细节：

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

rules:variables

  • 引入于 13.7 版本。
  • 功能标志移除于 13.10 版本。

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

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

可能的输入：格式为 VARIABLE-NAME: value 的变量哈希。

rules:variables 示例： 

job:
  variables:
    DEPLOY_VARIABLE: "default-deploy"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:                              # Override DEPLOY_VARIABLE defined
        DEPLOY_VARIABLE: "deploy-production"  # at the job level.
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Define a new variable.
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

only / except

noteonly 和 except 没有被积极开发。rules 是控制何时向流水线添加作业的首选关键字。

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

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

only:refs / except:refs

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

only:refs 和 except:refs 没有被积极开发。rules:if 是使用 refs、正则表达式或变量来控制何时将作业添加到流水线时的首选关键字。

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

可能的输入：一个包含任意数量的数组：

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

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

  • 以下关键词：

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

only:refs 和 except:refs 示例： 

job1:
  script: echo
  only:
    - main
    - /^issue-.*$/
    - merge_requests

job2:
  script: echo
  except:
    - main
    - /^stable-branch.*$/
    - schedules

额外细节：

  • 预定流水线在特定分支上运行，因此配置了 only: branch 的作业也可以在预定流水线上运行。添加 except: schedules 以防止带有 only: branch 的作业在预定流水线上运行。

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

    job1:
  script: echo
  only:
    - branches

job2:
  script: echo
  only:
    refs:
      - branches

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

    例如，job1 和 job2 是等价的： 

    job1:
  script: echo "test"

job2:
  script: echo "test"
  only:
    - branches
    - tags

only:variables / except:variables

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

only:variables 和 except:variables 没有被积极开发。rules:if 是使用 refs、正则表达式或变量来控制何时将作业添加到流水线时的首选关键字。

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

可能的输入：CI/CD 变量表达式的数组。

only:variables 示例： 

deploy:
  script: cap staging deploy
  only:
    variables:
      - $RELEASE == "staging"
      - $STAGING

only:changes / except:changes

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

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

  • branches
  • external_pull_requests
  • merge_requests

only:changes 和 except:changes 没有被积极开发。rules:if 是使用 refs、正则表达式或变量来控制何时将作业添加到流水线时的首选关键字。

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

可能的输入：一个包含任意数量的数组：

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

only:changes 示例： 

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - branches
    changes:
      - Dockerfile
      - docker/scripts/*
      - dockerfiles/**/*
      - more_scripts/*.{rb,py,sh}
      - "**/*.json"

额外细节：

  • 如果任何匹配的文件发生更改（OR 操作），changes 将解析为 true。
  • 如果使用除 branches、external_pull_requests 或 merge_requests 以外的引用，changes 无法确定给定文件是新文件还是旧文件，并且总是返回 true。
  • 如果您将 only: changes 与其他引用一起使用，作业将忽略更改并始终运行。
  • 如果您将 except: changes 与其他引用一起使用，作业将忽略更改并且永远不会运行。

only:kubernetes / except:kubernetes

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

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

可能的输入：kubernetes 策略只接受 active 关键字。

only:kubernetes 示例： 

deploy:
  only:
    kubernetes: active

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

needs

  • 引入于 12.2 版本。
  • 于 12.3 版本，needs 数组中的最大作业数从 5 增加到 50。
  • 于 12.8 版本，needs: [] 让作业立即开始。
  • 于 14.2 版本，您可以参考与您正在配置的作业处于同一阶段的作业。

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

您可以忽略阶段排序并运行一些作业，而无需等待其他作业完成。 多个阶段的作业可以同时运行。

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

可能的输入：

  • 一个数组的作业。
  • 一个空数组 ([])，用于将作业设置为在创建流水线后立即启动。

needs 示例： 

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

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

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

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

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

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

示例创建四个执行路径：

  • Linter：lint 作业立即运行，无需等待 build 阶段完成，因为它没有需求（needs: []）。
  • Linux 路径：linux:rspec 和 linux:rubocop 作业在 linux:build 作业完成后立即运行，无需等待 mac:build 完成。
  • macOS 路径：mac:rspec 和 mac:rubocop 作业在 mac:build 作业完成后立即运行，无需等待 linux:build 完成。
  • production 作业在所有先前的作业完成后立即运行；在这种情况下：linux:build、linux:rspec、linux:rubocop、mac:build、mac:rspec、mac:rubocop。

额外细节：

  • needs: 数组中单个作业可以需要的最大作业数是有限的：
    • 对于自助管理实例，默认限制为 50。此限制可以更改。
  • 如果 needs: 指的是使用 parallel 关键字的作业，它取决于并行创建的所有作业，而不仅仅是一个作业。 默认情况下，它还从所有并行作业下载产物。如果产物具有相同的名称，它们会相互覆盖，并且只保存最后下载的产物。
  • 在 14.1 及更高版本中，您可以引用与您正在配置的作业处于同一阶段的作业。在自助管理的 14.2 及更高版本上，此功能默认可用。
  • 在 14.0 及更早版本中，您只能引用早期阶段的作业。必须为所有使用 needs: 关键字或在作业的 needs: 部分中引用的作业明确定义阶段。
  • 在 13.9 及更早版本中，如果 needs: 指的是由于 only、except 或 rules 可能无法添加到流水线中的作业，则流水线可能无法创建。
  • 如果流水线有 needs: [] 的作业和处于 .pre 阶段的作业，它们将在流水线创建后立即启动。needs: [] 的作业立即开始，.pre 阶段的作业也立即开始。

needs:artifacts

当作业使用 needs 时，默认情况下它不再下载前一阶段的所有产物，因为带有 needs 的作业可以在早期阶段完成之前开始。使用 needs，您只能从 needs: 配置中列出的作业中下载产物。

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

关键字类型：作业关键字。您只能将其用作作业的一部分。 Must be used with needs:job.

可能的输入：

  • true（默认）或 false.

needs:artifacts 示例： 

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

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

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

在这个例子中：

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

额外细节：

  • 在 12.6 及更高版本中，您不能将 dependencies 关键字与 needs 结合使用。

needs:project

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

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

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

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

可能的输入：

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

needs:project 示例： 

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

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

在 13.3 及更高版本中，您可以在 needs:project 中使用 CI/CD 变量，例如： 

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: $CI_PROJECT_PATH
      job: $DEPENDENCY_JOB_NAME
      ref: $ARTIFACTS_DOWNLOAD_REF
      artifacts: true

额外细节：

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

needs:pipeline:job

引入于 13.7 版本。

子流水线 可以从其父流水线或同一父子流水线层次结构中的另一个子流水线中的作业下载产物。

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

可能的输入：

  • needs:pipeline：流水线 ID。必须是存在于同一父子流水线层次结构中的流水线。
  • job:：从中下载产物的作业。

needs:pipeline:job 示例：

  • 父流水线 (.gitlab-ci.yml)： 

    create-artifact:
  stage: build
  script: echo 'sample artifact' > artifact.txt
  artifacts:
    paths: [artifact.txt]

child-pipeline:
  stage: test
  trigger:
    include: child.yml
    strategy: depend
  variables:
    PARENT_PIPELINE_ID: $CI_PIPELINE_ID

  • 子流水线 (child.yml)： 

    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 中的变量从父流水线下载产物。

额外细节：

  • pipeline 属性不接受当前的流水线 ID ($CI_PIPELINE_ID)。要从当前流水线中的作业下载产物，请使用 needs。

needs:optional

  • 引入于 13.10 版本。
  • 功能标志移除于 14.0 版本。

如果需要有时在流水线中不存在的作业，请将 optional: true 添加到 needs 配置中。如果未定义，optional: false 是默认值。

使用 rules、only 或 except 的作业可能并不总是添加到流水线中。系统在启动流水线之前检查 needs 关系：

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

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

needs:optional 示例： 

build-job:
  stage: build

test-job1:
  stage: test

test-job2:
  stage: test
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
    - job: test-job1

review-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
  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:pipeline

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

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

可能的输入：

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

needs:pipeline 示例： 

upstream_bridge:
  stage: test
  needs:
    pipeline: other/project

额外细节：

  • 如果您将 job 关键字添加到 needs:pipeline，该作业将不再反映流水线状态。更改为 needs:pipeline:job。

tags

  • 于 14.3 版本，在自助管理版上启用的每个作业限制为 50 个标签。

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

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

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

可能的输入：

  • 标签名称数组。
  • 14.1 及更高版本中的 CI/CD 变量。

tags 示例： 

job:
  tags:
    - ruby
    - postgres

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

额外细节：

  • 在 14.3 及更高版本中，标签数量必须小于 50。

allow_failure

使用 allow_failure 来确定当作业失败时，流水线是否应该继续运行。

  • 要让流水线继续运行后续作业，请使用 allow_failure: true。
  • 要停止流水线运行后续作业，请使用 allow_failure: false。

当允许作业失败 (allow_failure: true) 时，橙色警告 () 表示作业失败。但是，流水线是成功的，并且关联的提交被标记为已通过且没有警告。

在以下情况下会显示相同的警告：

  • 阶段中的所有其他工作均成功。
  • 流水线中的所有其他作业均成功。

allow_failure 的默认值为：

  • 手动作业为 true。

  • 对于在 rules 中使用 when:manual 的作业为 false。
  • 在所有其它情况下为 false。

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

可能的输入：true 或 false。

allow_failure 示例： 

job1:
  stage: test
  script:
    - execute_script_1

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

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

在这个例子中，job1 和 job2 并行运行：

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

额外细节：

  • 您可以使用 allow_failure 作为 rules: 的子键。
  • 如果设置了 allow_failure: true，则作业始终被视为成功，如果此作业失败，则以后带有 when: on_failure 的作业不会启动。
  • 您可以在手动作业中使用 allow_failure: false 来创建阻塞的手动作业。在手动作业启动并成功完成之前，阻塞的流水线不会在后续阶段运行任何作业。

allow_failure:exit_codes

  • 引入于 13.8 版本。
  • 功能标志移除于 13.9 版本。

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

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

可能的输入：

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

allow_failure 示例： 

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

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

when

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

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

可能的输入：

  • on_success（默认）：仅当早期阶段的所有作业都成功或具有 allow_failure: true 时才运行作业。
  • manual：仅在手动触发时运行作业。
  • always：无论早期阶段的作业状态如何，都运行作业。也可以在 workflow:rules 中使用。
  • on_failure：只有在早期阶段至少有一个作业失败时才运行作业。带有 allow_failure: true 的作业总是被认为是成功的。
  • delayed：作业的执行延迟指定的持续时间。
  • never：不要运行作业。只能在 rules 部分或 workflow: rules 中使用。

when 示例： 

stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:
  stage: build
  script:
    - make build

cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
    - make test

deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual
  environment: production

cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always

在这个例子中，脚本：

  1. 只有当 build_job 失败时才执行 cleanup_build_job。
  2. 无论成功或失败，始终将 cleanup_job 作为流水线的最后一步执行。
  3. 在 GitLab UI 中手动运行时执行 deploy_job。

额外细节：

  • 在 13.5 及更高版本中，您可以在与 trigger 相同的作业中使用 when:manual。在 13.4 及更早版本中，将它们一起使用会导致错误 jobs:#{job-name} when should be on_success, on_failure or always。
  • allow_failure 的默认行为通过 when: manual 更改为 true。但是，如果您将 when: manual 与 rules 一起使用，allow_failure 默认为 false。

environment

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

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

可能的输入：作业部署到的环境的名称，采用以下格式之一：

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

environment 示例： 

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

额外细节：

  • 如果您指定了一个 environment 并且不存在具有该名称的环境，则会创建一个环境。

environment:name

为环境设置名称。

常见的环境名称是 qa、staging 和 production，但您可以使用任何名称。

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

可能的输入：作业部署到的环境的名称，采用以下格式之一：

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

environment:name 示例： 

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

environment:url

为环境设置 URL。

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

可能的输入：单个 URL，采用以下格式之一：

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

environment:url 示例： 

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

额外细节：

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

environment:on_stop

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

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

额外细节：

environment:action

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

值 描述
start 默认值。 表示作业启动环境。部署是在作业启动后创建的。
prepare 表示作业只准备环境。它不会触发部署。
stop 表示作业停止环境。请参阅下面的示例。
verify 表示作业只验证环境。它不会触发部署。
access 表示作业仅访问环境。它不会触发部署。

举例： 

review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop_review_app

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

在上面的例子中，review_app 作业部署到 review 环境。在 on_stop 下列出了一个新的 stop_review_app 作业。在 review_app 作业完成后，它会根据 when 下定义的内容触发 stop_review_app 作业。在这种情况下，它被设置为 manual，因此它需要来自 GitLab UI 的手动操作运行。

同样在示例中，GIT_STRATEGY 设置为 none。如果 stop_review_app 作业自动触发，则 runner 在删除分支后不会尝试检出代码。

该示例还覆盖了全局变量。如果您的 stop environment 作业依赖于全局变量，请在设置 GIT_STRATEGY 且在不覆盖全局变量的情况下，更改作业时使用锚点变量。

stop_review_app 作业需要定义以下关键字：

此外，两个作业都应该具有匹配的 rules 或 only/except 配置。

在上面的示例中，如果配置不相同：

  • stop_review_app 作业可能不会包含在包含 review_app 作业的所有流水线中。
  • 无法触发 action: stop 来自动停止环境。

environment:auto_stop_in

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

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

可能的输入：用自然语言编写的一段时间。 例如，这些都是等价的：

  • 168 hours
  • 7 days
  • one week
  • never

environment:auto_stop_in 示例： 

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

当为 review_app 创建环境时，环境的生命周期设置为 1 day。 每次部署 review app 时，该生命周期也会重置为 1 day。

environment:kubernetes

使用 kubernetes 关键字将部署配置到与您的项目关联的 Kubernetes 集群。

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

environment:kubernetes 示例： 

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      namespace: production

此配置使用 production Kubernetes 命名空间。

额外细节：

  • 由极狐GitLab 管理 的 Kubernetes 集群不支持 Kubernetes 配置。

environment:deployment_tier

引入于 13.10 版本。

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

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

可能的输入：以下之一：

  • production
  • staging
  • testing
  • development
  • other

environment:deployment_tier 示例： 

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

额外细节：

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

动态环境

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

例如： 

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

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

常见的用例是为分支机构创建动态环境并将它们用作审核应用程序。

cache

引入于 15.0 版本，缓存不在受保护和未受保护的分支之间共享。

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

缓存：

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

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

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

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

cache:paths

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

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

可能的输入：相对于项目目录的路径数组（$CI_PROJECT_DIR）。您可以使用使用 glob 模式的通配符：

cache:paths 示例：

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

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

额外细节：

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

cache:key

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

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

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

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

可能的输入：

cache:key 示例： 

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

额外细节：

  • 如果你使用 Windows Batch 运行你的 shell 脚本，你需要用 % 替换 $。 例如：密钥：%CI_COMMIT_REF_SLUG%

  • cache:key 值不能包含：

    • / 字符，或等效的 URI 编码的 %2F。
    • 只有 . 字符（任何数字），或等效的 URI 编码的 %2E。
  • 缓存在作业之间共享，因此如果您为不同的作业使用不同的路径，您还应该设置不同的 cache:key。 否则缓存内容可能会被覆盖。
cache:key:files

使用 cache:key:files 关键字在一两个特定文件更改时生成新密钥。cache:key:files 可让您重用一些缓存，并减少重建它们的频率，从而加快后续流水线运行的速度。

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

可能的输入：一个或两个文件路径的数组。

cache:key:files 示例： 

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key:
      files:
        - Gemfile.lock
        - package.json
    paths:
      - vendor/ruby
      - node_modules

此示例为 Ruby 和 Node.js 依赖项创建缓存。缓存绑定到当前版本的 Gemfile.lock 和 package.json 文件。当这些文件之一发生变化时，将计算一个新的缓存键并创建一个新的缓存。任何使用相同的 Gemfile.lock 和 package.json 以及 cache:key:files 的未来作业都会使用新的缓存，而不是重建依赖项。

额外信息：缓存 key 是根据最近更改了每个列出的文件的提交计算得出的 SHA。如果在任何提交中都没有更改任何文件，则回退键是 default。

cache:key:prefix

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

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

可能的输入：

cache:key:prefix 示例： 

rspec:
  script:
    - echo "This rspec job uses a cache."
  cache:
    key:
      files:
        - Gemfile.lock
      prefix: $CI_JOB_NAME
    paths:
      - 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 仓库中所有未跟踪的文件：

未跟踪的文件包括以下文件：

如果作业下载以下文件，缓存未跟踪的文件会产生意想不到的大缓存：

  • 依赖项，如 gem 或节点模块，通常未被跟踪。
  • 来自不同作业的产物。默认情况下，未跟踪从产物中提取的文件。

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

可能的输入：true 或 false（默认）。

cache:untracked 示例： 

rspec:
  script: test
  cache:
    untracked: true

额外细节：

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

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

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

cache:unprotect

引入于 15.8 版本。

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

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

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

可能的输入：

  • true 或 false（默认值）

cache:unprotect 示例： 

rspec:
  script: test
  cache:
    unprotect: true

cache:when

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

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

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

可能的输入：

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

cache:when 示例： 

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

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

cache:policy

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

要将作业设置为仅在作业开始时下载缓存，但在作业完成时从不上传更改，请使用 cache:policy:pull。

要将作业设置为仅在作业完成时上传缓存，但在作业开始时从不下载缓存，请使用 cache:policy:push。

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

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

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

可能的输入：

  • pull
  • push
  • pull-push（默认）

cache:policy 示例： 

prepare-dependencies-job:
  stage: build
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: push
  script:
    - echo "This job only downloads dependencies and builds the cache."
    - echo "Downloading dependencies..."

faster-test-job:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - echo "This job script uses the cache, but does not update it."
    - echo "Running tests..."

dependencies

使用 dependencies 关键字定义要从中获取产物的作业列表。 您还可以设置一个作业以完全不下载任何产物。

如果您不使用 dependencies，则前一阶段的所有产物都会传递给每个作业。

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

可能的输入：

  • 从中获取产物的作业名称。
  • 一个空数组 ([])，用于将作业配置为不下载任何产物。

dependencies 示例： 

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

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

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

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

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

在这个例子中，两个作业有产物：build osx 和 build linux。当执行 test osx 时，build osx 的产物被下载并在构建的上下文中提取。 同样的事情发生在 test linux 和 build linux 的产物上。

由于 stage 优先级，deploy 作业从所有以前的作业下载产物。

额外细节：

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

artifacts

使用 artifacts 指定在作业 succeeds, fails, 或 always 时附加到作业的文件和目录列表。

作业完成后，产物将发送到 GitLab。如果大小不大于最大产物大小，它们可以在 GitLab UI 中下载。

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

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

默认只收集成功作业的作业产物，产物在缓存后恢复。

阅读有关产物的更多信息。

artifacts:exclude

exclude 可以防止将文件添加到产物存档中。

类似于 artifacts:paths，exclude 路径是相对于项目目录的。您可以使用使用 glob 或 doublestar.PathMatch 模式的通配符。

例如，要将所有文件存储在 binaries/ 中，但不存储位于 binaries/ 子目录中的 *.o 文件： 

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

与 artifacts:paths 不同，exclude 路径不是递归的。要排除目录的所有内容，您可以显式匹配它们而不是匹配目录本身。

例如，要将所有文件存储在 binaries/ 中，但不存储在 temp/ 子目录中： 

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/temp/**/*

与 artifacts:untracked 匹配的文件也可以使用 artifacts:exclude 排除。

artifacts:expire_in

  • 引入于 13.0 版本，在功能标志后默认禁用，无论到期时间如何，都会保留最新的作业产物。
  • 默认启用于 13.4.
  • 引入于 13.8 版本，可以在项目级别禁用保持最新的作业产物。
  • 引入于 13.9 版本，可以在实例范围内禁用保持最新的作业产物。
  • 引入于 13.12 版本，无论到期时间如何，都会保留最新的流水线产物。

使用 expire_in 指定作业产物在它们过期和被删除之前存储多长时间。expire_in 设置不会影响：

  • 来自最新作业的产物，除非保留最新的作业产物：
    • 在项目级别禁用。
    • 在实例范围禁用。
  • 流水线产物。无法为这些指定到期日期：
    • 来自最新流水线的流水线产物将永远保留。
    • 一周后删除其他流水线产物。

expire_in 的值是以秒为单位的经过时间，除非提供了单位。有效值包括：

  • '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

要在上传后一周使产物过期： 

job:
  artifacts:
    expire_in: 1 week

当产物上传并存储在极狐GitLab 上时，到期时间段开始。如果未定义到期时间，则默认为实例范围设置（默认为 30 天）。

要覆盖到期日期并保护产物不被自动删除：

  • 使用作业页面上的保留按钮。
  • 在 13.3 及更高版本中，将 expire_in 的值设置为 never。

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

artifacts:expose_as

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

例如，要匹配单个文件： 

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

通过此配置，极狐GitLab 添加了一个链接 artifact 1 到指向 file1.txt 的相关合并请求。要访问该链接，请选择合并请求概览中流水线图下方的 查看已展示的产物。

匹配整个目录的示例： 

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

请注意以下事项：

  • 使用变量定义 artifacts:paths 时，不会在合并请求 UI 中显示产物。
  • 每个合并请求最多可以公开 10 个作业产物。
  • 不支持全局模式。
  • 如果指定了目录，如果目录中有多个文件，则链接指向作业产物浏览器。
  • 对于带有 .html、.htm、.txt、.json、.xml 和 .log 扩展名的公开单个文件产物，如果 GitLab Pages：
    • 启用，系统自动呈现产物。
    • 未启用，文件显示在产物浏览器中。

artifacts:name

使用 name 指令来定义创建的产物存档的名称。您可以为每个存档指定唯一的名称。artifacts:name 变量可以使用任何预定义变量。 默认名称是 artifacts，下载后会变成 artifacts.zip。

要使用当前作业的名称创建存档： 

job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/

要使用当前分支或标记的名称创建档案，仅包括二进制目录： 

job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

如果您的分支名称包含正斜杠（例如feature/my-feature），建议使用 $CI_COMMIT_REF_SLUG 而不是 $CI_COMMIT_REF_NAME 来正确命名产物。

要使用当前作业的名称和当前的分支或标记创建仅包含二进制文件目录的存档： 

job:
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

要使用当前 stage 和分支名称的名称创建存档： 

job:
  artifacts:
    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

如果您使用 Windows Batch 运行您的 shell 脚本，你需要用 % 替换 $： 

job:
  artifacts:
    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
    paths:
      - binaries/

如果您使用 Windows PowerShell 运行您的 shell 脚本，你需要用 $env: 替换 $： 

job:
  artifacts:
    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
    paths:
      - binaries/

artifacts:paths

路径相对于项目目录 ($CI_PROJECT_DIR)，不能直接链接到项目目录之外。您可以使用 glob 模式的通配符和：

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

发送 binaries 和 .config 中的所有文件： 

artifacts:
  paths:
    - binaries/
    - .config

要禁用产物传递，请使用空 dependencies 定义作业： 

job:
  stage: build
  script: make build
  dependencies: []

您可能只想为标签版本创建产物，以避免使用临时构建产物填充构建服务器存储。

仅为标签创建产物（default-job 不创建产物）： 

default-job:
  script:
    - mvn test -U
  rules:
    - if: $CI_COMMIT_BRANCH

release-job:
  script:
    - mvn package -U
  artifacts:
    paths:
      - target/*.war
  rules:
    - if: $CI_COMMIT_TAG

您也可以对目录使用通配符。例如，如果您想获取以 xyz 结尾的目录中的所有文件： 

job:
  artifacts:
    paths:
      - path/*xyz/*

artifacts:public

  • 引入于 13.8 版本，部署在功能标志 non_public_artifacts 后，默认禁用。
  • 更新于 15.10 版本，不能保证在 15.10 之前使用 artifacts:public 创建的产物在此更新后保持私有。
在私有化部署实例上，默认情况下此功能不可用。要使其可用，请让管理员启用命名为 non_public_artifacts 的功能标志 。在 SaaS 版上，此功能不可用。

使用 artifacts:public 来确定作业产物是否应该公开可用。

artifacts:public 的默认值为 true，这意味着匿名和访客用户可以下载公共流水线中的产物： 

artifacts:
  public: true

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

artifacts:
  public: false

artifacts:reports

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

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

可能的输入：

artifacts:reports 示例： 

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

额外细节：

  • 不支持使用来自子流水线的产物结合父流水线中的报告。
  • 为了能够浏览报告输出文件，请包含 artifacts:paths 关键字，将上传和存储产物两次。
  • 为 artifacts: reports 创建的产物总是被上传，不论作业结果成功或失败。您可以使用 artifacts:expire_in 设置产物的到期日期。
artifacts:reports:accessibility

accessibility 报告使用 pa11y 报告合并请求中引入的更改对可访问性的影响。

极狐GitLab 可以在合并请求可访问性部件中显示一个或多个报告的结果。

artifacts:reports:api_fuzzing

api_fuzzing 报告收集了 API Fuzzing bug 作为产物。

artifacts:reports:browser_performance
  • 名称从 artifacts:reports:performance 改为现名称于 14.0 版本。

browser_performance 报告收集浏览器性能测试指标作为产物。

极狐GitLab 可以在合并请求中显示一份报告的结果。

极狐GitLab 无法显示多个 browser_performance 报告的组合结果。

artifacts:reports:cluster_image_scanning
  • 引入于 14.1 版本。
  • 需要 GitLab Runner 14.1 和更高版本。

cluster_image_scanning 报告收集 CLUSTER_IMAGE_SCANNING 漏洞作为产物。

artifacts:reports:cobertura

cobertura 报告收集 Cobertura 覆盖 XML 文件。 收集的 Cobertura 覆盖率报告作为产物上传到极狐GitLab 并显示在合并请求中。

Cobertura 最初是为 Java 开发的，但有许多第三方移植用于其他语言，如 JavaScript、Python、Ruby 等。

artifacts:reports:codequality

codequality 报告收集代码质量问题作为产物。

收集的代码质量报告作为产物上传到极狐GitLab，并在合并请求中汇总。

artifacts:reports:container_scanning

container_scanning 报告收集容器扫描漏洞作为产物。

收集的容器扫描报告作为产物上传到极狐GitLab，并在合并请求和流水线视图中汇总。它还用于为安全仪表盘提供数据。

artifacts:reports:coverage_fuzzing

coverage_fuzzing 报告收集 coverage fuzzing bug。 收集到的覆盖模糊报告作为产物上传到极狐GitLab。

artifacts:reports:dast

dast 报告收集 DAST 漏洞。收集的 DAST 报告作为产物上传到极狐GitLab。

artifacts:reports:dependency_scanning

dependency_scanning` 报告收集依赖扫描漏洞。 收集到的依赖扫描报告作为产物上传到极狐GitLab。

artifacts:reports:dotenv

收集的变量被注册为作业的运行时创建的变量，这对于作业完成后设置动态环境 URL 很有用。

原始 dotenv 规则 有几个例外：

  • 变量键只能包含字母、数字和下划线 (_)。
  • .env 文件的最大大小为 5 KB。
  • 在 13.5 及更早版本中，最大继承变量数为 10。
  • 在 13.6 及更高版本中，最大继承变量数为 20。
  • 不支持.env 文件中的变量替换。
  • .env 文件不能有空行或注释（以 # 开头）。
  • env 文件中的键值不能有空格或换行符 (\n)，包括使用单引号或双引号时。
  • 不支持在解析过程中引用转义 (key = 'value' -> {key: "value"})。
artifacts:reports:junit

junit 报告收集JUnit 报告格式 XML 文件。 收集到的单元测试报告作为产物上传到极狐GitLab。尽管 JUnit 最初是用 Java 开发的，但也有许多其他语言（如 JavaScript、Python 和 Ruby）的第三方端口。

下面是从 Ruby 的 RSpec 测试工具收集 JUnit 报告格式 XML 文件的示例： 

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

一些 JUnit 工具导出到多个 XML 文件。您可以在单个作业中指定多个测试报告路径以将它们连接到一个文件中。使用：

  • 文件名模式（junit: rspec-*.xml）。
  • 文件名数组（junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]）。
  • 两者的组合（junit: [rspec.xml, test-results/TEST-*.xml]）。
artifacts:reports:license_scanning

许可证合规报告收集许可证。许可证合规报告作为产物上传到极狐GitLab。

artifacts:reports:load_performance

load_performance 报告收集负载性能测试指标作为产物。

该报告作为产物上传到极狐GitLab。

artifacts:reports:metrics

metrics 报告收集 Metrics 作为产物。

收集的指标报告作为产物上传到极狐GitLab。

artifacts:reports:requirements

requirements 报告收集 requirements.json 文件作为产物。

收集到的需求报告作为产物上传到极狐GitLab，现有的需求被标记为 Satisfied。

artifacts:reports:sast

sast 报告收集 SAST 漏洞作为产物。

收集的 SAST 报告作为产物上传到极狐GitLab，并在合并请求和流水线视图中汇总。它还用于为安全仪表盘提供数据。

artifacts:reports:secret_detection

secret-detection 报告收集检测到的 secret 作为产物。

收集到的 secret 检测报告作为产物上传到极狐GitLab，并在合并请求和流水线视图中汇总。它还用于为安全仪表盘提供数据。

artifacts:reports:terraform
  • 引入于 13.0 版本。
  • 需要极狐GitLab Runner 11.5 及更高版本。

terraform 报告获取 Terraform tfplan.json 文件。删除凭据所需的 JQ 流程。收集的 Terraform 计划报告作为产物上传到极狐GitLab。

artifacts:untracked

使用 artifacts:untracked 将所有 Git 未跟踪文件添加为产物（以及在 artifacts:paths 中定义的路径）。artifacts:untracked 忽略仓库的 .gitignore 文件中的配置。

发送所有 Git 未跟踪文件： 

artifacts:
  untracked: true

发送所有 Git 未跟踪文件和 binaries 中的文件： 

artifacts:
  untracked: true
  paths:
    - binaries/

发送所有未跟踪的文件，但排除 *.txt： 

artifacts:
  untracked: true
  exclude:
    - "*.txt"

artifacts:when

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

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

可能的输入：

  • on_success（默认）：仅在作业成功时上传产物。
  • on_failure：仅在作业失败时上传产物。
  • always：始终上传产物（作业超时时除外）。例如，当 上传产物需要对失败的测试进行故障排除时。

artifacts:when 示例： 

job:
  artifacts:
    when: on_failure

额外细节：

  • 为 artifacts:reports 创建的产物总是被上传，无论作业结果（成功或失败）如何。artifacts:when 不会改变这种行为。

coverage

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

为了提取匹配行中的代码覆盖率值，极狐GitLab 使用以下正则表达式：\d+(\.\d+)?。

可能的输入：正则表达式。必须以/开头和结尾。

coverage 示例： 

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

在这个例子中：

  1. 系统检查作业日志中是否有与正则表达式匹配的行。像 Code coverage: 67.89 这样的行会匹配。
  2. 然后检查该行以找到与 \d+(\.\d+)? 的匹配项。上面的示例匹配行给出了 67.89 的代码覆盖率。

额外细节：

  • 如果作业输出中有多个匹配的行，则使用最后一行。
  • 如果单行中有多个匹配项，则搜索使用最后一个匹配项。
  • 如果在匹配的片段中找到多个覆盖率数字，则使用第一个。
  • 删除前导零。
  • 子流水线的覆盖输出未记录或显示。

dast_configuration

引入于 14.1 版本。

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

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

可能的输入：site_profile 和 scanner_profile 各一个。

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

dast_configuration 示例： 

stages:
  - build
  - dast

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

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

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

额外细节：

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

retry

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

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

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

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

可能的输入：0（默认）、1 或2。

retry 示例： 

test:
  script: rspec
  retry: 2

retry:when

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

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

可能的输入：单一故障类型，或一个或多个故障类型的数组：

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

retry:when 示例（单一故障型）: 

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

果存在除 runner 系统故障以外的故障，则不会重试作业。

retry:when 示例 （故障类型数组）: 

test:
  script: rspec
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure

timeout

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

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

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

可能的输入：用自然语言编写的一段时间。例如，以下都是等价的：

  • 3600 seconds
  • 60 minutes
  • one hour

timeout 示例： 

build:
  script: build.sh
  timeout: 3 hours 30 minutes

test:
  script: rspec
  timeout: 3h 30m

parallel

从 15.9 版本开始，parallel 的最大值从 50 增加到 200。

使用 parallel 配置并行运行的作业实例数。

parallel 关键字创建并行运行的同一作业的 N 个实例。 它们从 job_name 1/N 到 job_name N/N 按顺序命名：

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

可能的输入：从 2 到 200 的数值。

parallel 示例： 

test:
  script: rspec
  parallel: 5

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

额外细节：

  • 每个并行作业都有一个 CI_NODE_INDEX 和 CI_NODE_TOTAL 预定义 CI/CD 变量集。

parallel:matrix

从 15.9 版本开始，最大排列数从 50 增加到 200。

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

必须存在多个 runner，或者必须将单个 runner 配置为同时运行多个作业。

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

可能的输入：变量哈希数组：

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

parallel:matrix 示例： 

deploystacks:
  stage: deploy
  script:
    - bin/deploy
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2
      - PROVIDER: ovh
        STACK: [monitoring, backup, app]
      - PROVIDER: [gcp, vultr]
        STACK: [data, processing]
  environment: $PROVIDER/$STACK

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

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

Additional details:

  • parallel:matrix 作业将变量值添加到作业名称以区分作业，但较大的值可能会导致名称超出限制：

trigger

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

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

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

可能的输入：

  • 对于多项目流水线，指向下游项目的路径。在 15.3 及更高版本中 支持 CI/CD 变量，但不支持作业级持久变量。
  • 对于子流水线，子流水线 CI/CD 配置文件的路径。

trigger 示例： 

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

额外细节：

  • 您不能使用 API 来启动 when:manual 触发器作业。
  • 在 13.5 及更高版本中，您可以在与 trigger 相同的作业中使用 when:manual。 在 13.4 及更早版本中，将它们一起使用会导致错误 jobs:#{job-name} when should be on_success, on_failure or always。
  • 在 13.2 及更高版本中，您可以在流水线图中查看哪个作业触发了下游流水线。
  • 手动流水线变量和计划流水线变量默认情况下不传递给下游流水线。使用 trigger:forward 将这些变量转发到下游流水线。
  • 作业级持久变量在触发器作业中不可用。

trigger:include

使用 trigger:include 声明作业是启动子流水线 的“触发作业”。

使用 trigger:include:artifact 触发动态子流水线。

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

可能的输入：

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

trigger:include 的示例： 

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

trigger:project

使用 trigger:project 声明作业是启动多项目流水线 的“触发作业”。

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

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

可能的输入：

trigger:project 示例： 

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

不同分支的 trigger:project 示例： 

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

trigger:strategy

使用 trigger:strategy 强制 trigger 作业在标记为 success 之前等待下游流水线完成。

此行为与默认行为不同，默认行为是在创建下游流水线后立即将 trigger 作业标记为 success。

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

trigger:strategy 示例： 

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

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

额外细节：

  • 下游流水线中的可选手动作业不影响下游流水线或上游触发作业的状态。下游流水线无需运行任何可选的手动作业即可成功完成。
  • 下游流水线中的阻塞手动作业必须在触发作业被标记为成功或失败之前运行。如果由于手动作业，下游流水线状态为 等待手动操作 ()，则触发器作业显示 等待中 ()。默认情况下，在触发作业完成之前，后续阶段的作业不会启动。

interruptible

如果在作业完成之前新流水线启动时应取消作业，请使用 interruptible。

如果禁用自动取消冗余流水线，则此关键字无效。启用后，在为同一分支上的新更改启动流水线时，会取消正在运行的具有 interruptible: true 的作业。

在带有 interruptible: false 的作业开始后，您无法取消后续作业。

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

可能的输入：true 或 false（默认）。

interruptible 示例： 

stages:
  - stage1
  - stage2
  - stage3

step-1:
  stage: stage1
  script:
    - echo "Can be canceled."
  interruptible: true

step-2:
  stage: stage2
  script:
    - echo "Can not be canceled."

step-3:
  stage: stage3
  script:
    - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible."
  interruptible: true

在这个例子中，一个新的流水线导致一个正在运行的流水线：

  • 取消，如果只有 step-1 正在运行或挂起。
  • 未取消，在 step-2 开始后。

额外细节：

  • 如果作业在开始后可以安全取消，则仅设置 interruptible: true，例如构建作业。通常不应取消部署作业，以防止部分部署。
  • 要完全取消正在运行的流水线，所有作业必须具有 interruptible: true，或 interruptible: false 作业必须尚未启动。

resource_group

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

例如，如果属于同一资源组的多个作业同时排队，则只有其中一个作业启动。其他作业一直等到 resource_group 空闲。

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

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

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

可能的输入：只有字母、数字、-、_、/、$、{、}、. 和空格。不能以/开头或结尾。

resource_group 示例： 

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

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

release

使用 release 创建一个发布。

发布作业必须有权访问 release-cli，其必须在 $PATH 中。

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

可能的输入：release: 子键：

release 关键字示例： 

release_job:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG                  # Run this job when a tag is created manually
  script:
    - echo "Running the release job."
  release:
    tag_name: $CI_COMMIT_TAG
    name: 'Release $CI_COMMIT_TAG'
    description: 'Release created using the release-cli.'

此示例创建一个版本：

  • 当你推送一个 Git 标签时。
  • 当您在 仓库 > 标签 的 UI 中添加 Git 标签时。

额外细节：

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

    script:
  - echo 'release job'
  • release 部分在 script 关键字之后和 after_script 之前执行。
  • 仅当作业的主脚本成功时才会创建发布。
  • 如果发布已经存在，则不会更新并且带有 release 关键字的作业失败。

release:tag_name

必需的。发布的 Git 标签。

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

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

可能的输入：标签名称。可以使用 CI/CD 流水线。

release:tag_name 示例：

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

  • 使用 $CI_COMMIT_TAG CI/CD 变量作为 tag_name。
  • 使用 rules:if 或 only: tags 将作业配置为仅针对新标签运行。 
job:
  script: echo 'Running the release job for the new tag.'
  release:
    tag_name: $CI_COMMIT_TAG
    description: 'Release description'
  rules:
    - if: $CI_COMMIT_TAG

要同时创建发布和新标签，您的 rules 或 only 应该不应将作业配置为仅针对新标签运行。语义版本控制示例： 

job:
  script: echo 'Running the release job and creating a new tag.'
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: 'Release description'
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

release:tag_message

引入于 15.3 版本。release-cli v0.12.0 或更高版本支持。

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

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

可能的输入：

  • 一个文本字符串。

release:tag_message 示例： 

  release_job:
    stage: release
    release:
      tag_name: $CI_COMMIT_TAG
      description: 'Release description'
      tag_message: 'Annotated tag message'

release:name

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

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

可能的输入：一个文本字符串。

release:name 示例： 

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

release:description

发布的详细说明。

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

可能的输入：

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

release:description 示例： 

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

release:ref

如果 release: tag_name 还不存在，作为发布的 ref。

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

可能的输入：

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

release:milestones

与发布相关的每个里程碑的标题。

release:released_at

发布准备就绪的日期和时间。

可能的输入：

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

release:released_at 示例： 

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

额外细节：

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

引入于 13.12 版本。

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

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

release:assets:links 示例： 

assets:
  links:
    - name: 'asset1'
      url: 'https://example.com/assets/1'
    - name: 'asset2'
      url: 'https://example.com/assets/2'
      filepath: '/pretty/url/1' # optional
      link_type: 'other' # optional

secrets

引入于 13.4 版本。

使用 secrets 将 CI/CD secret 指定为：

此关键字必须与 secrets:vault 一起使用。

secrets:vault

  • 引入于 13.4 版本和 GitLab Runner 13.4。

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

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

可能的输入：

  • engine:name：secret engine 的名称。
  • engine:path：secret engine 的路径。
  • path：secret 的路径。
  • field：存储密码的字段的名称。

secrets:vault 示例：

要明确指定所有详细信息并使用 KV-V2 secret engine： 

job:
  secrets:
    DATABASE_PASSWORD:  # Store the path to the secret in this CI/CD variable
      vault:  # Translates to secret: `ops/data/production/db`, field: `password`
        engine:
          name: kv-v2
          path: ops
        path: production/db
        field: password

您可以缩短此语法。 使用简短的语法，engine:name 和 engine:path 都默认为 kv-v2： 

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`

要以简短的语法指定自定义 secret engine 路径，请添加以 @ 开头的后缀： 

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:file

引入于 14.1 版本和 GitLab Runner 14.1.

使用 secrets:file 配置 secret 存储为 file 或 variable 类型 CI/CD 变量。

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

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

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

可能的输入：true（默认）或 false。

secrets:file 示例： 

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

额外细节：

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

secrets:token

引入于 15.8 版本。

通过引用令牌的 CI/CD 变量，使用 secrets:token 明确选择要在使用 Vault 进行身份验证时使用的令牌。

如果禁用 限制 JSON Web Token (JWT) 访问，则此关键字无效。

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

可能的输入：

  • ID 令牌的名称

secrets:token 示例： 

job:
  id_tokens:
    AWS_TOKEN:
      aud: https://aws.example.com
    VAULT_TOKEN:
      aud: https://vault.example.com
  secrets:
    DB_PASSWORD:
      vault: gitlab/production/db
      token: $VAULT_TOKEN

额外细节：

  • 当未设置 token 关键字并启用 限制 JSON Web Token (JWT) 访问 时，将使用第一个 ID 令牌进行身份验证。
  • 当禁用 限制 JSON Web Token (JWT) 访问 时，将忽略 token 关键字并使用 CI_JOB_JWT CI/CD 变量进行身份验证。

pages

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

关键字类型：作业名称。

pages 示例： 

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

此示例将所有文件从项目的根目录移动到 public/ 目录。 .public 的解决方法是，cp 不会在无限循环中将 public/ 复制到自身。

额外细节：

你必须：

  • 将任何静态内容放在 public/ 目录中。
  • 定义 artifacts 和 public/ 目录的路径。

inherit

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

inherit:default

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

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

可能的输入：

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

inherit:default 示例： 

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

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

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

额外细节：

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

inherit:variables

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

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

可能的输入：

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

inherit:variables 示例： 

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

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

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

额外细节：

  • 您还可以在一行中列出要继承的全局变量：variables: [VARIABLE1, VARIABLE2]

trigger:forward

  • 引入于 14.9 版本，功能标志名为 ci_trigger_forward_variables。默认禁用。
  • 在 SaaS 版和私有化部署版上启用于 14.10 版本。
  • 一般可用于 15.1 版本。功能标志 ci_trigger_forward_variables 删除。

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

可能的输入：

  • yaml_variables：true（默认），或 false。当为 true 时，触发器作业中定义的变量被传递到下游流水线。
  • pipeline_variables: true 或 false（默认）。当为 true 时，手动流水线变量和计划流水线变量被传递到下游流水线。

trigger:forward 示例：

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

variables: # default variables for each job
  VAR: value

# Default behavior:
# - VAR is passed to the child
# - MYVAR is not passed to the child
child1:
  trigger:
    include: .child-pipeline.yml

# Forward pipeline variables:
# - VAR is passed to the child
# - MYVAR is passed to the child
child2:
  trigger:
    include: .child-pipeline.yml
    forward:
      pipeline_variables: true

# Do not forward YAML variables:
# - VAR is not passed to the child
# - MYVAR is not passed to the child
child3:
  trigger:
    include: .child-pipeline.yml
    forward:
      yaml_variables: false

variables

使用 variables 为作业定义自定义变量。

变量在 script、before_script 和 after_script 命令中始终可用。 您还可以在某些作业关键字中使用变量作为输入。

关键字类型：全局和工作关键字。您可以在全局级别使用它，也可以在作业级别使用它。

如果您将 variables 定义为全局关键字，它的行为类似于所有作业的默认变量。创建流水线时，每个变量都会复制到每个作业配置。 如果作业已经定义了该变量，则作业级别变量优先。

在全局级别定义的变量不能用作其他全局关键字的输入，例如 include。这些变量只能在作业级别使用，在 script、before_script 和 after_script 部分，以及一些作业关键字中的输入，例如 rules。

可能的输入：变量名和值对：

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

variables 示例： 

variables:
  DEPLOY_SITE: "https://example.com/"

deploy_job:
  stage: deploy
  script:
    - deploy-script --url $DEPLOY_SITE --path "/"
  environment: production

deploy_review_job:
  stage: deploy
  variables:
    REVIEW_PATH: "/review"
  script:
    - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH
  environment: production

额外细节：

variables:description

引入于 13.7 版本。

使用 description 关键字定义流水线级（全局）变量的描述。 描述显示手动运行流水线时预填入的变量名称。

关键字类型：全局关键字。当您手动运行流水线时，您无法将作业级变量设置为预填入。

可能的输入：一个字符串。

variables:description 示例： 

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

额外细节：

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

variables:value

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

关键字类型：全局关键字。您不能将它用于作业级变量。

可能的输入：一个字符串。

variables:value 示例： 

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

额外细节：

variables:options

引入于 15.7 版本。

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

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

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

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

关键字类型：全局关键字。您不能将它用于作业级变量。

可能的输入：字符串的数组。

variables:options 示例： 

variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    options:
      - "production"
      - "staging"
      - "canary"
    description: "The deployment target. Set to 'staging' by default."

variables:expand

  • 引入于 15.6 版本，功能标志为 ci_raw_variables_in_yaml_config。默认禁用。
  • 在 SaaS 版上启用于 15.6 版本。
  • 在私有化部署版上启用于 15.7 版本。
  • 一般可用于 15.8 版本。功能标志 ci_raw_variables_in_yaml_config 已删除。

使用 expand 关键字将变量配置为可扩展或不可扩展。

关键字类型：全局和作业关键字。您可以在全局级别和作业级别使用它。

可能的输入：

  • true（默认）：变量可扩展。
  • false：变量不可扩展。

variables:expand 示例： 

variables:
  VAR1: value1
  VAR2: value2 $VAR1
  VAR3:
    value: value3 $VAR1
    expand: false
  • VAR2 的结果是 value2 value1。
  • VAR3 的结果是 value3 $VAR1。

额外细节：

废弃的关键字

以下关键字已弃用。

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

不推荐在全局范围内定义 image、services、cache、before_script 和 after_script。可能会从未来的版本中删除支持。

使用 default: 代替。 例如： 

default:
  image: ruby:3.0
  services:
    - docker:dind
  cache:
    paths: [vendor/]
  before_script:
    - bundle config set path vendor/bundle
    - bundle install
  after_script:
    - rm -rf tmp/