CI/CD YAML 语法参考

本文档列出了极狐GitLab .gitlab-ci.yml 文件的配置选项。此文件是您定义 CI/CD 作业以组成流水线的关键。

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

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

关键字

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

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

全局关键字

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

default

  • 对 id_tokens 的支持引入于极狐GitLab 16.4。

您可以为某些关键字设置全局默认值。 未定义一个或多个所列关键字的作业使用在 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: 部分覆盖了默认值：

在示例中：

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

额外细节：

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

include

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

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

include 文件：

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

解决所有文件的时间限制为 30s。

Keyword type: 全局关键字

可能的输入： include 子关键字：

还有可选地：

额外详情:

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

include:component

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

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

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

include:component 示例：

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

相关主题:

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 子目录路径包含本地文件。
  • include 配置始终基于包含 include 关键字的文件的位置进行评估，而不是运行流水线的项目。如果 嵌套 include 在另一个项目中的配置文件中，include: local 会检查其他项目中的文件。

include:project

要想在同一个实例上，从其他私有项目包含文件，使用 include:project 和 include:file。

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

可能的输入：

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

include:project 示例：

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

您还可以指定 ref：

include:
  - project: 'my-group/my-project'
    ref: main                                      # Git 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'

额外的信息：

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

include:remote

使用 include:remote 和一个完整的 URL 来从不同的地方包含文件。

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

可能的输入：

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

Example of include:remote:

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

额外信息：

  • 所有嵌套包含内容都会以公共用户的身份在无上下文的环境下执行，因此你只能包含公共项目或模板。在嵌套包含内容的 include 部分中，无法使用任何变量。
  • 当从其他项目 CI/CD 配置中包含时要小心。当其他项目的文件更改时，不会触发流水线或通知。从安全角度来看，这类似于拉取第三方依赖项。如果你链接到你拥有的另一个 GitLab 项目，请考虑同时使用保护分支和保护标签来强制执行变更管理规则。

include:template

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

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

可能的输入：

CI/CD 模板:

include:template 示例：

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

Multiple include:template files:

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

额外信息：

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

include:inputs

  • 引入于极狐GitLab 15.11，作为 Beta 功能。
  • 在极狐GitLab 17.0 中 GA。

当包含的配置使用 spec:inputs时，可以使用 include:inputs 来为输出参数设置值并添加到流水线中。

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

可能的输入：字符、数字或布尔值。

include:inputs 示例：

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

在此示例中：

  • 包含在 custom_configuration.yml 中的配置被添加到流水线中，使用 website 将包含的配置的值设置为 My website。

额外的信息：

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

相关主题：

include:rules

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

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

可能的输入：这些 rules 子 key：

支持有些 CI/CD 变量。

include:rules 示例：

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

test-job:
  stage: test
  script: echo "This is a test job"

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

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

相关主题：

stages

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

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

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

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

如果流水线在 .pre 或 .post 阶段中包含任何作业，则它不会运行。必须要在不同的阶段中要有其他作业。.pre 和 .post 阶段可以在必需的流水线配置中使用，以定义必须在项目流水线作业之前或之后运行的合规作业。

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

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 来控制流水线行为。

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

相关主题：

workflow:auto_cancel:on_new_commit

  • 引入于极狐GitLab 16.8，使用名为 ci_workflow_auto_cancel_on_new_commit 的功能标志。默认禁用。
  • 在极狐GitLab 16.9中，为私有化部署和 JihuLab.com 启用。
  • 在极狐GitLab 16.10 中 GA。功能标志 ci_workflow_auto_cancel_on_new_commit 被移除。

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

可能的输入：

  • conservative：取消流水线，但只有在没有 interruptible: false 的作业已经开始时才取消。默认情况下未定义。
  • interruptible：仅取消 interruptible: true 的作业。
  • none：不取消任何作业。

workflow:auto_cancel:on_new_commit 示例：

workflow:
  auto_cancel:
    on_new_commit: interruptible

job1:
  interruptible: true
  script: sleep 60

job2:
  interruptible: false  # Default when not defined.
  script: sleep 60

在此示例中：

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

workflow:auto_cancel:on_job_failure

  • 引入于极狐GitLab 16.0，使用名为 auto_cancel_pipeline_on_job_failure 的功能标志。默认禁用。
  • 在极狐GitLab 16.10 中 GA。功能标志 auto_cancel_pipeline_on_job_failure 被移除。

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

可能的输入：

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

workflow:auto_cancel:on_job_failure 示例：

stages: [stage_a, stage_b]

workflow:
  auto_cancel:
    on_job_failure: all

job1:
  stage: stage_a
  script: sleep 60

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

job3:
  stage: stage_b
  script:
    - sleep 30

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

相关主题：

workflow:name

  • 引入于 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 关键字类似于 jobs 中定义的 rules，但控制是否创建整个流水线。

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

可能的输入：您可以将有些相同关键字作为作业级别的 rules：

workflow:rules 示例：

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

在此示例中，如果提交标题（提交消息的第一行）不以 -draft 结尾，则流水线将运行，且流水线是：

  • 针对合并请求
  • 针对默认分支

额外信息：

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

相关主题：

workflow:rules:variables

您可以在 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 并列出要转发到下游流水线的确切变量。

workflow:rules:auto_cancel

  • 引入于极狐GitLab 16.8，使用名为 ci_workflow_auto_cancel_on_new_commit 的功能标志。默认禁用。
  • 在极狐GitLab 16.9 上为 JihuLab.com 和私有化部署可用。
  • 在极狐GitLab 16.10 中 GA。功能标志 ci_workflow_auto_cancel_on_new_commit 被移除。
  • workflow:rules 中的 on_job_failure 选项引入于极狐GitLab 16.10，使用名为 auto_cancel_pipeline_on_job_failure 的功能标志。默认禁用。
  • workflow:rules 中的 on_job_failure 选项在极狐GitLab 16.11 中 GA。功能标志 auto_cancel_pipeline_on_job_failure 被移除。

使用 workflow:rules:auto_cancel 来配置 workflow:auto_cancel:on_new_commit 或 workflow:auto_cancel:on_job_failure功能。

可能输入：:

workflow:rules:auto_cancel 示例：

workflow:
  auto_cancel:
    on_new_commit: interruptible
    on_job_failure: all
  rules:
    - if: $CI_COMMIT_REF_PROTECTED == 'true'
      auto_cancel:
        on_new_commit: none
        on_job_failure: none
    - when: always                  # Run the pipeline in other cases

test-job1:
  script: sleep 10
  interruptible: false

test-job2:
  script: sleep 10
  interruptible: true

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

  • 一个非受保护的分支，并且有新的提交，test-job1 继续运行，test-job2 被取消。
  • 一个受保护的分支，并且有新的提交，test-job1 和 test-job2 都继续运行。

标头关键字

有些关键字必须定义在 YAML 配置文件中的标头部分。标头必须在文件顶部，使用 --- 与配置的其余部分分开。

spec

  • 引入于极狐GitLab 15.11，作为 Beta 功能。

添加 spec 部分到 YAML 文件中的标头中来配置当使用 include 关键字将配置添加到流水线时的流水线行为。使用 include:inputs 来定义当流水线运行时使用的值。

spec:inputs

您可以使用 spec:inputs 来定义您打算使用 include 添加到流水线的 CI/CD 配置的输入参数。使用 include:inputs 来定义流水线运行时使用的值。

当在 CI/CD 配置中使用时，可以使用输入自定义配置的行为。

使用插值格式 $[[ inputs.input-id ]] 来引用头部区域之外的值。在流水线创建期间获取配置时，但在该配置与 .gitlab-ci.yml 文件内容合并之前，会对输入项进行评估和插值处理。

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

可能的输入：代表期望输入的字符哈希。

spec:inputs 示例：

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

scan-website:
  stage: $[[ inputs.job-stage ]]
  script: ./scan-website $[[ inputs.environment ]]

额外信息：

  • 输入是强制性的，除非您使用 spec:inputs:default 设置默认值。
  • 输入期望字符串，除非您使用 spec:inputs:type 设置不同的输入类型。
  • 包含插值块的字符串不能超过 1 MB。
  • 插值块内的字符串不能超过 1 KB。

相关主题：

spec:inputs:default
  • 引入于极狐GitLab 15.11，作为 Beta 功能。

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

对于没有默认值的表述，可使用 default: ''。

关键字类型：标头关键字。必需在配置文件的顶部、标头部分被声明。

可能的输入：代表默认值的字符串，或 ''。

spec:inputs:default 示例：

spec:
  inputs:
    website:
    user:
      default: 'test-user'
    flags:
      default: ''
---

# The pipeline configuration would follow...

在此示例中：

  • website 是强制性的，必须定义。
  • user 是可选的。如果没有定义，值为 test-user。
  • flags 是可选的。如果没有定义，它没有值。

额外信息:

  • 当输入处于如下状况时，流水线由于验证错误而失败：
    • 同时使用 default 和 options，但默认值不是列出的选项之一。
    • 同时使用 default 和 regex，但默认值与正则表达式不匹配。
    • 值与 type 不匹配。
spec:inputs:description
  • 引入于极狐GitLab 16.5。

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

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

可能输入：代表描述的字符串。

spec:inputs:description 示例：

spec:
  inputs:
    flags:
      description: 'Sample description of the `flags` input details.'
---

# The pipeline configuration would follow...
spec:inputs:options
  • 引入于极狐GitLab 16.6。

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

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

可能的输入：输入选项数组。

spec:inputs:options 示例：

spec:
  inputs:
    environment:
      options:
        - development
        - staging
        - production
---

# The pipeline configuration would follow...

在此示例中：

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

额外信息：

  • 当发生以下情况时，流水线由于验证错误而失败：
    • 输入同时使用 options 和 default，但默认值不是列出的选项之一。
    • 输入的任意选项与 type 不匹配，该类型可以是 string 或 number，但不能是 boolean。
spec:inputs:regex
  • 引入于极狐GitLab 16.5。

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

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

可能输入：必须为正则表达式。

spec:inputs:regex 示例：

spec:
  inputs:
    version:
      regex: ^v\d\.\d+(\.\d+)$
---

# The pipeline configuration would follow...

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

额外信息：

  • inputs:regex 只能和 string type 一起使用，而不是 number 或 boolean。
  • 不要用 / 字符包围正则表达式。例如，使用 regex.*，而不是 /regex.*/。
  • inputs:regex 使用 RE2 来解析正则表达式。
spec:inputs:type

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

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

可能的输入：可以是以下中的一种：

  • array，接受输入数组。
  • string，接受字符输入（当未定义时使用默认值）。
  • number，接受数字输入。
  • boolean，仅接受 true 或 false 输入。

spec:inputs:type 示例：

spec:
  inputs:
    job_name:
    website:
      type: string
    port:
      type: number
    available:
      type: boolean
    array_input:
      type: array
---

# The pipeline configuration would follow...

作业关键字

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

after_script

  • 运行 after_script 命令来取消作业引入于极狐GitLab 17.0。

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

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

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

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

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 命令的支持。

相关主题：

allow_failure

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

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

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

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

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

allow_failure 的默认值为：

  • 手动作业为 true。

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

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

可能的输入：true 或 false。

allow_failure 示例：

job1:
  stage: test
  script:
    - execute_script_1

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

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

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

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

额外细节：

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

allow_failure:exit_codes

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

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

可能的输入：

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

allow_failure 示例：

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

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

artifacts

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

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

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

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

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

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

artifacts:paths

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

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

可能的输入：

  • 相对于项目目录的文件数组路径。
  • 你可以使用采用通配符模式的通配符，并且：

CI/CD 变量是受支持的。

artifacts:paths 示例：

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

此示例会创建一个 .config 的产物且所有的文件都在 binaries 目录中。

额外信息：

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

相关主题：

artifacts:exclude

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

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

可能的输入：

artifacts:exclude 示例：

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

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

额外信息：

  • artifacts:exclude 路径无法递归搜索。
  • 通过 artifacts:untracked 匹配的文件可以使用 artifacts:exclude 进行排出。

相关主题：

artifacts:expire_in

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

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

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

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

可能的输入：到期时间。如果没有提供单位，则时间以秒为单位。有效值包括：

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

artifacts:expire_in 示例：

job:
  artifacts:
    expire_in: 1 week

额外细节：

  • 过期时间段从产物上传并存储到极狐GitLab 时开始。如果未定义到期时间，则默认为实例范围设置。
  • 要覆盖过期日期并保护产物不被自动删除：
    • 在作业页面上选择 保留。
    • 在 13.3 及更高版本，将 expire_in 的值设置为 never。

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

  • 引入于 13.8 版本，部署在功能标志 non_public_artifacts 后，默认禁用。
  • 更新于 15.10 版本，不能保证在 15.10 之前使用 artifacts:public 创建的产物在此更新后保持私有。
caution 在私有化部署实例上，默认情况下此功能不可用。要使其可用，请让管理员启用命名为 non_public_artifacts 的功能标志 。在 SaaS 版上，此功能不可用。当功能标志被禁用时可以使用关键字，但该功能不起作用。当功能标志被禁用时，请勿尝试使用此功能，并且始终首先使用非生产数据进行测试。

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

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

artifacts:
  public: true

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

artifacts:
  public: false

artifacts:access

  • 引入于极狐GitLab 16.11。

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

您无法在相同的作业中使用 artifacts:public 和 artifacts:access。

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

可能的输入：

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

artifacts:access 示例:

job:
  artifacts:
    access: 'developer'

额外信息:

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

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

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

可能的输入：

  • true 或 false （如未定义，使用默认值）

artifacts:untracked 示例：

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

job:
  artifacts:
    untracked: true

相关主题:

artifacts:when

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

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

可能的输入：

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

artifacts:when 示例：

job:
  artifacts:
    when: on_failure

额外细节：

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

before_script

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

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

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

CI/CD 变量是受支持的。

before_script 示例：

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

额外细节：

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

相关主题：

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

  • 引入极狐GitLab 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: 部分 中使用。

可能的输入：

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..."

相关主题：

cache:fallback_keys

使用 cache:fallback_keys 指定一个键列表，如果没有找到 cache:key 的缓存，则尝试恢复缓存。缓存按照 fallback_keys 部分中指定的顺序检索。

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

可能的输入：

  • 缓存键数组

cache:fallback_keys 示例：

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

coverage

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

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

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

coverage 示例：

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

在这个例子中：

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

额外细节：

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

dast_configuration

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

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

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

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

dast_configuration 示例：

stages:
  - build
  - dast

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

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

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

额外细节：

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

相关主题：

dependencies

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

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

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

可能的输入：

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

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 作业从所有以前的作业下载产物。

额外细节：

  • 作业状态无关紧要。如果作业失败或者是未触发的手动作业，则不会发生错误。
  • 如果依赖作业的产物是已过期或已删除，则作业失败。
  • 要从相同阶段的作业获取产物，您必须使用 needs:artifacts。您不应在同一作业中同时使用 dependencies 和 needs。

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 表示作业仅访问环境。它不会触发部署。

environment:action 示例：

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

environment:auto_stop_in

  • CI/CD 变量支持引入于极狐GitLab 15.4。

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

  • agent 关键字引入于极狐GitLab 17.6。

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

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

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

可能的输入：以下之一：

  • production
  • staging
  • testing
  • development
  • other

environment:deployment_tier 示例：

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

额外细节：

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

Related topics:

动态环境

使用 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 访问该环境。

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

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 是一个隐藏作业，但也可以从常规作业扩展配置。

相关主题：

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'

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

可能的输入：包含以下内容的数组：

CI/CD 变量是受支持的d。

hooks:pre_get_sources_script 示例：

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

相关主题：

identity

  • 引入于极狐GitLab 16.9，使用名为 google_cloud_support_feature_flag 的功能标志。默认禁用。
  • 在极狐GitLab 17.1 为 JihuLab.com 启用。功能标志 google_cloud_support_feature_flag 被移除。

功能处于 beta。

使用 identity 使用身份联合认证与第三方服务进行身份验证。

关键字类型：作业关键字。您可以将其作为作业的一部分或在 default: section中使用。

可能的输入：一个身份标识。支持的提供商有：

identity 示例：

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

相关主题：

id_tokens

  • 引入于极狐GitLab 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:entrypoint

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

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

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

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

image:entrypoint 示例：

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

相关主题：

image:docker

  • 引入于极狐GitLab 16.7。需要极狐GitLab Runner 16.7 及更高版本。
  • user 输入选项引入于极狐GitLab 16.8。

使用 image:docker 将选项传递给极狐GitLab Runner 的 Docker 执行器。

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

可能的输入：

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

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

image:docker 示例：

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

额外信息:

image:pull_policy

  • 引入于 15.1 版本，功能标志为 ci_docker_image_pull_policy。默认禁用。
  • 在极狐GitLab 15.2 中，为 JihuLab.com 或私有化部署启用。
  • 在极狐GitLab 15.4 中 GA。功能标志 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])。

相关主题：

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]

interruptible

  • 引入于极狐GitLab 16.8。

使用 interruptible 可以配置 自动取消冗余流水线 功能，在同一 ref 启动新流水线时取消作业，如果新流水线的提交比正在运行的流水线的提交更新，则取消作业。如果禁用该功能，则关键字无效。新流水线必须为提交新更改。例如，如果在 UI 中选择 New pipeline 来运行同一提交的流水线，则 自动取消冗余流水线 功能不会生效。

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

关键字类型：作业关键字。您只能将其用作作业的一部分或在 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，例如构建作业。部署作业通常不应被取消，以防止部分部署。
  • 当使用默认行为或 workflow:auto_cancel:on_new_commit: conservative 时：
    • 尚未启动的作业始终被视为 interruptible: true，无论作业的配置如何。只有在作业启动后才会考虑 interruptible 配置。
    • 运行流水线只有在所有正在运行的作业都配置为 interruptible: true 或在任何时间都没有启动过配置为 interruptible: false 的作业时才会被取消。具有 interruptible: false 的作业启动后，整个流水线不再被认为是可中断的。
    • 如果流水线触发了一个下游流水线，但下游流水线中没有启动过配置为 interruptible: false 的作业，那么下游流水线也会被取消。
  • 您可以添加一个可选的具有 interruptible: false 的手动作业作为流水线的第一个阶段，以允许用户手动防止流水线被自动取消。在用户启动作业后，流水线无法被 自动取消冗余流水线 功能取消。
  • 当与 trigger job 一起使用 interruptible 时：
    • 触发的下游流水线永远不会受到触发作业的 interruptible 配置的影响。
    • 如果 workflow:auto_cancel 设置为 conservative，则触发作业的 interruptible 配置没有效果。
    • 如果 workflow:auto_cancel 设置为 interruptible，则具有 interruptible: true 的触发作业可以被自动取消。

needs

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

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

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

可能的输入：

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

needs 示例：

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

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

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

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

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

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

示例创建四个执行路径：

  • Linter：lint 作业立即运行，无需等待 build 阶段完成，因为它没有需求（needs: []）。
  • Linux 路径：linux:rspec 和 linux: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 关键字的作业，它取决于并行创建的所有作业，而不仅仅是一个作业。 默认情况下，它还从所有并行作业下载产物。如果产物具有相同的名称，它们会相互覆盖，并且只保存最后下载的产物。
    • 要使 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 的作业中下载产物。

关键字类型：作业关键字。您只能将其用作作业的一部分。 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。

额外细节：

  • 您不能将 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 作业下载产物。

您可以在 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: 中运行的作业下载产物。
  • 在 project、job 和 ref 中的支持CI/CD 变量的支持。

相关主题：

needs:pipeline:job

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

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

可能的输入：

  • 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:pipeline:job，或从多项目流水线中下载产物。要从多项目流水线中下载产物，请使用 needs:project。

needs:optional

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

使用 rules、only 或 except、或添加了 include 的作业可能并不总是添加到流水线中。系统在启动流水线之前检查 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 示例：

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_status:
  stage: test
  needs:
    pipeline: other/project

额外细节：

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

needs:parallel:matrix

  • 引入于极狐GitLab 16.3。

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

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

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

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

  • 变量和值必须从 parallel:matrix 作业中定义的变量和值中选择。

needs:parallel:matrix 示例:

linux:build:
  stage: build
  script: echo "Building linux..."
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2

linux:rspec:
  stage: test
  needs:
    - job: linux:build
      parallel:
        matrix:
          - PROVIDER: aws
            STACK: app1
  script: echo "Running rspec on linux..."

以上示例生成以下作业：

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

linux:build: [aws, app1] 作业失败时，linux:rspec 作业运行。

相关主题:

额外信息:

  • needs:parallel:matrix 中的矩阵变量顺序必须与所需作业中的矩阵变量顺序匹配。例如，将以下示例中的 linux:rspec 作业中的变量顺序反转是无效的：

    linux:rspec:
  stage: test
  needs:
    - job: linux:build
      parallel:
        matrix:
          - STACK: app1        # The variable order does not match `linux:build` and is invalid.
            PROVIDER: aws
  script: echo "Running rspec on linux..."

pages

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

您必须：

  • 定义 artifacts 并指定内容目录的路径，默认为 public。
  • 如果您使用不同内容目录，则使用 artifacts。

关键字类型：作业名称。

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/ 目录的路径。

pages:publish

  • 引入于极狐GitLab 16.1。

使用 publish 配置 pages 作业的内容目录。

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

可能的输入：包含页面内容的目录的路径。

publish 示例：

pages:
  stage: deploy
  script:
    - npx @11ty/eleventy --input=path/to/eleventy/root --output=dist
  artifacts:
    paths:
      - dist
  publish: dist
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

此示例使用 Eleventy 生成静态网站，并将生成的 HTML 文件输出到 dist/ 目录。该目录被导出为工件，并与极狐GitLab Pages 一起发布。

pages:pages.path_prefix

  • 引入于极狐GitLab 16.7，作为实验功能，使用名为 pages_multiple_versions_setting 的功能标志，默认禁用。
  • 在极狐GitLab 17.4 中为 JihuLab.com 和私有化部署启用。
此功能的可用性受控于功能标志。更多信息，可以查看历史。此功能仅为测试用，还未生产就绪。

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

关键字类型：作业关键字。您可以将其用作 pages 作业的一部分。

可能的输入：字符，CI/CD 变量，或两者组合。给定值转换为小写，缩短为 63 个字节，并用连字符替换所有非字母数字字符。不允许前导和尾随连字符。

pages.path_prefix 示例：

pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}/${CI_COMMIT_BRANCH}"
  pages:
    path_prefix: "$CI_COMMIT_BRANCH"
  artifacts:
    paths:
    - public

在此示例中，每个分支都会创建一个不同的 pages 部署。

pages:pages.expire_in

  • 引入于极狐GitLab 17.4。

使用 expire_in 指定部署应该可用多长时间。过期后，部署将由每 10 分钟运行一次的 cron 作业停用。

默认情况下，额外部署会过期。要防止它们过期，请将其设置为 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

pages:pages.expire_in 示例：

pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  pages:
    expire_in: 1 week
  artifacts:
    paths:
      - public

parallel

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

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

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

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

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

parallel 示例：

test:
  script: rspec
  parallel: 5

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

额外细节：

  • 每个并行作业都有一个 CI_NODE_INDEX 和 CI_NODE_TOTAL 预定义 CI/CD 变量集。
  • 使用 parallel 作业的流水线可以：
    • 创建比可用 runner 更多的并行运行的作业。多余的作业将排队并标记为 pending，直到有可用的 runner。
    • 创建过多的作业，流水线失败并出现 job_activity_limit_exceeded 错误。在活跃流水线中可以存在的最大作业数是实例级别限制的。

相关主题：

parallel:matrix

  • 从 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 作业将变量值添加到作业名称以区分作业，但较大的值可能会导致名称超出限制：

  • 您无法创建多个具有相同变量值、不同变量名的矩阵配置。作业名称由变量值生成，而不是变量名，因此具有相同值的矩阵条目生成相同作业名称，从而覆盖彼此。

    比如，这个 test 配置会尝试创建两个相同的作业系列，但是 OS2 版本会覆盖 OS 版本：

    test:
  parallel:
    matrix:
      - OS: [ubuntu]
        PROVIDER: [aws, gcp]
      - OS2: [ubuntu]
        PROVIDER: [aws, gcp]

相关主题：

release

使用 release 创建一个发布。

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

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

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

可能的输入：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。

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

可能的输入：

  • 标签名称。

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'

额外细节：

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

release:ref

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

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

可能的输入：

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

release:milestones

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

release:released_at

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

可能的输入：

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

release:released_at 示例：

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

额外细节：

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

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

resource_group

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

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

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

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

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

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

resource_group 示例：

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

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

retry

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

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

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

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

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

retry 示例：

test:
  script: rspec
  retry: 2

test_advanced:
  script:
    - echo "Run a script that results in exit code 137."
    - exit 137
  retry:
    max: 2
    when: runner_system_failure
    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：当发生下面情况时重试：
    • 脚本失败。
    • 对于 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

retry:exit_codes

  • 引入于极狐GitLab 16.10，使用名为 ci_retry_on_exit_codes 功能标志。默认禁用。
  • 在极狐GitLab 16.11 中为 JihuLab.com 和私有化部署启用。
  • 在极狐GitLab 17.5 中 GA。功能标志 ci_retry_on_exit_codes 被移除。

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

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

可能的输入：

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

retry:exit_codes 示例：

test_job_1:
  script:
    - echo "Run a script that results in exit code 1. This job isn't retried."
    - exit 1
  retry:
    max: 2
    exit_codes: 137

test_job_2:
  script:
    - echo "Run a script that results in exit code 137. This job will be retried."
    - exit 137
  retry:
    max: 1
    exit_codes:
      - 255
      - 137

相关主题：

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

rules

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

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

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

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

rules 接受以下规则：

  • if
  • changes
  • exists
  • when

Rules 还可以和以下关键字结合使用：

  • allow_failure
  • needs
  • variables
  • interruptible

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

作业被添加到流水线中：

  • 如果 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 语句的评估：

关键字类型：特定于作业和特定于流水线。您可以将其用作作业的一部分来配置作业行为，或者使用 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 通过检查对特定文件的更改来指定何时将作业添加到流水线。

对新分支流水线或没有 Git push 事件的流水线，rules: changes 总是评估为 true，作业总是运行。没有 Git push 事件的流水线，例如标记流水线、计划流水线和手动流水线，都不会运行。要涵盖这些情况，请使用 rules: changes: compare_to 指定与流水线 ref 进行比较的分支。

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

  • 合并请求流水线，rules:changes 将变更与目标 MR 分支进行比较。
  • 分支流水线，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

docker build alternative:
  variables:
    DOCKERFILES_DIR: 'path/to/dockerfiles'
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - $DOCKERFILES_DIR/**/*

在示例中：

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

额外细节：

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

相关主题：

rules:changes:paths
  • 引入于 15.2 版本。

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

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

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

可能的输入：

  • 查看上述中 rules:changes 的可能输入。

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 已删除。
  • 对于 CI/CD 变量的支持引入于极狐GitLab 17.2 版本。

使用 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 作业。

额外信息：

  • compare_to 和合并结果流水线一起使用可引起非期望的结果，因为比较基础是极狐GitLab 创建的内部提交。

相关主题：

rules:exists

  • 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

job2:
  variables:
    DOCKERPATH: "**/Dockerfile"
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        - $DOCKERPATH

在此示例中：

  • job1 在仓库的根目录中存在 Dockerfile 时运行。
  • job2 在仓库的任何位置存在 Dockerfile 时运行。

额外细节：

  • CI/CD 变量和 rules:exists 一起使用会有一些限制：
    • 您不能将嵌套变量与 exists 一起使用。
    • 在某些情况下，您不能在 exists 中使用带有 CI/CD 变量的 / 或 ./。
  • Glob 模式使用 Ruby 的 File.fnmatch，使用标志 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB。
  • 由于性能原因，极狐GitLab 对 exists 模式或文件路径执行的最大检查次数为 10,000 次。第 10,000 次检查后，规则中的模式总是匹配。换句话说，在包含超过 10,000 个文件的项目中，exists 规则始终假设匹配，或者如果文件少于 10,000 个但检查 exists 规则超过 10,000 次，则始终匹配。
    • 如果存在多个模式化的 globs，则限制为 10,000 除以 globs 的数量。例如，具有 4 个模式化 globs 的规则具有 2500 个文件限制。
  • 每个 rules:exists 部分最多可以定义 50 个模式或文件路径。
  • 如果列出的任何文件被找到，则 exists 解析为 true（OR 操作）。
  • 使用作业级别 rules:exists 时，极狐GitLab 会在运行流水线的项目和 ref 中搜索文件。当使用 include with rules:exists 时，GitLab 会在包含 include 部分的文件所在的项目和 ref 中搜索文件。包含 include 部分的项目可以与运行流水线的项目不同，当使用：
  • rules:exists 不能搜索产物的存在，因为 rules 评估发生在作业运行之前和工件被提取之前。
rules:exists:paths
  • 引入于极狐GitLab 16.11，使用名为 ci_support_rules_exists_paths_and_project 的功能标志。默认禁用。
  • 在极狐GitLab 17.0 中 GA。ci_support_rules_exists_paths_and_project 功能标志被移除。

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

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

可能输入：

  • 文件路径数组。

rules:exists:paths 示例：

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

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

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

额外信息：

  • 在有些情况下，您不能在 exists 中使用带有 CI/CD 变量的 / 或 ./。
rules:exists:project
  • 引入于极狐GitLab 16.11，使用名为 ci_support_rules_exists_paths_and_project 的功能标志。默认禁用。
  • 在极狐GitLab 17.0 中 GA。功能标志 ci_support_rules_exists_paths_and_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 示例：

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        paths:
          - Dockerfile
        project: my-group/my-project
        ref: v1.0.0

在此示例中，仅当 Dockerfile 存在于项目 my-group/my-project 中的提交 v1.0.0 上时，才包含 docker build 作业。

rules:when

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

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

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

可能输入：

  • on_success（默认）：仅当早期阶段中的作业未失败时才运行作业。
  • on_failure：仅当早期阶段中的作业失败时才运行作业。
  • never：无论早期阶段中的作业状态如何，都不运行作业。
  • always：无论早期阶段中的作业状态如何，都运行作业。
  • manual：将作业添加到流水线作为手动作业。allow_failure 的默认值更改为 false。
  • delayed：将作业添加到流水线作为延迟作业。

rules:when 示例：

job1:
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      when: delayed
    - when: manual
  script:
    - echo

在此示例中，job1 被添加到流水线中：

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

额外信息：

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

  • 引入于 16.0 版本，功能标志为 introduce_rules_with_needs。默认禁用。
  • 在极狐GitLab 16.2 中 GA，功能标志 introduce_rules_with_needs 被移除。

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

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

可能的输入：

  • 作为字符串的作业名称数组。
  • 带有作业名称的哈希值，可选地带有附加属性。
  • 一个空数组（[]），当满足特定条件时将作业设置为无。

rules:needs 示例：

build-dev:
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
  script: echo "Feature branch, so building dev version..."

build-prod:
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script: echo "Default branch, so building prod version..."

specs:
  stage: test
  needs: ['build-dev']
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      needs: ['build-prod']
    - when: on_success # Run the job in other cases
  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 示例：

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"

rules:interruptible

  • 引入于极狐GitLab 16.10。

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

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

可能的输入：

  • true 或 false.

rules:interruptible 示例：

job:
  script: echo "Hello, Rules!"
  interruptible: true
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      interruptible: false  # Override interruptible defined at the job level.
    - when: on_success

额外信息：

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

run (EXPERIMENTAL)

  • 引入于极狐GitLab 17.3，使用名为 pipeline_run_keyword 的功能标志。默认禁用。
  • 在极狐GitLab 17.5 中移除了功能标志 pipeline_run_keyword。
note 此功能仅为测试用，还未生产就绪。

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

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

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

可能的输入：

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

每个哈希条目都必需有一个 name、script 或 step（但不能同时有两者）。

run 示例：

job:
  run:
    - name: 'hello_steps'
      script: 'echo "hello from step1"'
    - name: 'bye_steps'
      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@main
      inputs:
        echo: 'bye steps!'
      env:
        var1: 'value 1'

在此示例中，作业有两步：

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

额外信息：

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

script

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

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

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

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

script 示例：

job1:
  script: "bundle exec rspec"

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

额外细节：

相关主题：

secrets

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

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

secrets:vault

  • generic 引擎选项引入于极狐GitLab 16.11。

使用 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:gcp_secret_manager

  • 引入于极狐GitLab 16.8 和极狐GitLab Runner 16.8。

使用 secrets:gcp_secret_manager 指定由 GCP Secret Manager 提供的 secret。

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

可能输入：

  • name：密钥名称。
  • version：密钥版本。

secrets:gcp_secret_manager 示例：

job:
  secrets:
    DATABASE_PASSWORD:
      gcp_secret_manager:
        name: 'test'
        version: 2

相关主题：

secrets:file

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

  • 引入于极狐GitLab 15.8，受控于 限制 JSON Web Token (JWT) 访问 设置。
  • 在极狐GitLab 16.0 中 GA，限制 JSON Web Token (JWT) 访问 设置被移除。

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

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

可能的输入：

  • 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 关键字时，将使用第一个 ID 令牌进行身份验证。

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 数据库。

相关主题：

services:docker

  • 引入于极狐GitLab 16.7。需要极狐GitLab 16.7 或更高版本。
  • user 输入选项引入于极狐GitLab 16.8。

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

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

可能输入：

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

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

services:docker 示例：

arm-sql-job:
  script: echo "Run sql tests in service container"
  image: ruby:2.6
  services:
    - name: super/sql:experimental
      docker:
        platform: arm64/v8
        user: dave

额外选项：

service:pull_policy

  • 引入于 15.1 版本，功能标志为 ci_docker_image_pull_policy。默认禁用。
  • 在 SaaS 版和私有化部署版上启用于 15.2 版本。
  • 在极狐GitLab 15.4 中 GA。功能标志 ci_docker_image_pull_policy 被移除。
  • 需要极狐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])。

相关主题：

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: [] 的作业会立即启动，忽略任何阶段配置。

tags

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

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

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

可能的输入：

tags 示例：

job:
  tags:
    - ruby
    - postgres

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

额外细节：

  • 标签数量必须小于 50。

相关主题：

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

trigger

  • 对于 environment 的支持引入于极狐GitLab 16.4。

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

触发作业只能使用一组有限的极狐GitLab 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

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

额外细节：

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

trigger:forward

  • 一般可用于 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

额外信息：

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

variables

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

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

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

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

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

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

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

CI/CD 变量是受支持的。

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:
    DEPLOY_SITE: "https://dev.example.com/"
    REVIEW_PATH: "/review"
  script:
    - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH
  environment: production

额外细节：

相关主题：

variables:description

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

额外细节：

when

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

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

可能的输入：

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

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。

额外细节：

  • 当为 on_success 和 on_failure 评估作业状态时：
    • 在早期阶段具有 allow_failure: true 的作业始终被认为是成功的。
    • 跳过早期阶段的作业，例如未启动的手动作业，始终被认为是成功的。

相关主题：

  • when 可以和 rules 一起使用以动态控制作业。
  • when 可以和 workflow 一起使用以控制流水线何时开始。

manual_confirmation

  • 引入于极狐GitLab 17.1。

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

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

可能输入：

  • 确认消息字符串。

manual_confirmation 示例：

delete_job:
  stage: post-deployment
  script:
    - make delete
  when: manual
  manual_confirmation: 'Are you sure you want to delete $CI_ENVIRONMENT_SLUG?'

废弃的关键字

以下关键字已弃用。

note 这些关键字依旧可用以确保向后兼容性，但是它们可能会在未来的版本中被删除。

全局定义的 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/

only / except

note only 和 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 中，从项目的 构建 > 流水线 部分选择 运行流水线 创建的流水线。

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 服务处于活动状态时运行。