这是此页面的过期版本。你可以查看最新版本或浏览历史。

`.codechina-ci.yml`文件的关键字参考

本文档包含.codechina-ci.yml文件中的配置选项。

当你在编辑.codechina-ci.yml的过程中，你可以通过 CI Lint 工具进行验证。

流水线任务关键字

流水线任务是由一系列定义了流水线任务行为的关键词组成的。

可用于流水线任务的关键字包括：

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

不可用的流水线任务名称

以下关键词不可用作流水线任务的名称：

image
services
stages
types
before_script
after_script
variables
cache
include

自定义默认关键字值

你可以为某些关键字设置全局默认值。未定义一个或多个所列关键字的流水线任务使用default:中定义的值。

以下这些流水线任务关键字可以在default:部分中定义：

after_script
artifacts
before_script
cache
image
interruptible
retry
services
tags
timeout

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

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

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

全局关键字

某些关键字在流水线任务中未定义，这些关键字控制流水线的行为或者导入额外的流水线配置：

关键字	描述
`stages`	流水线阶段的名称和顺序
`workflow`	控制运行的流水线类型
`include`	从其他 YAML 文件导入配置

`stages`

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

stages 的顺序定义了流水线任务的执行顺序：

同一阶段的流水线任务并行运行
下一阶段的流水线任务在上一阶段的流水线任务成功完成后运行

例如：

stages:
  - build
  - test
  - deploy

build 中所有的流水线任务并行执行。
如果 build 中的所有流水线任务都成功，则test中的流水线任务并行执行。
如果 test 中的所有流水线任务都成功，则deploy中的流水线任务并行执行。
如果 deploy 中的所有流水线任务都成功，则流水线标记为通过。

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

如果 .codechina-ci.yml 文件中没有定义 stages，则 build,test和 deploy 是默认的流水线阶段。

如果流水线任务未指定 stage，则将该流水线任务分配至test阶段。

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

stage 可以在合规性配置中定义，但如果不使用则保持隐藏。
当开发人员在流水线任务定义中使用它们时，定义的 stage 变得可见。

要使流水线任务更早开始并忽略 stage 顺序，请使用needs关键字。

`workflow`

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

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

workflow: rules 接受以下这些关键字：

if：检查此 rules 以确定何时运行流水线。
when：指定当 if rules 评估为真时要做什么。
- 要运行流水线，请设置为 always。
- 要防止流水线运行，请设置为 never。
variables: 如果未定义，则使用别处定义的变量。

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

workflow: rules的一些示例if条款：

示例 `rules`	描述
`if: '$CI_PIPELINE_SOURCE == "merge_request_event"'`	控制合并请求流水线何时运行
`if: '$CI_PIPELINE_SOURCE == "push"'`	控制分支流水线和 Tag 流水线何时运行
`if: $CI_COMMIT_TAG`	控制 Tag 流水线何时运行
`if: $CI_COMMIT_BRANCH`	控制分支流水线何时运行

有关更多示例，请参阅通用 if rules 条款。

在以下示例中，流水线针对所有 push 事件（对分支和新标签的更改）运行。提交消息中含-draft的推送事件不会运行流水线，因为它们被设置为when: never。计划或合并请求的流水线也不会运行，因为没有 rules 对它们评估为真：

workflow:
  rules:
    - if: $CI_COMMIT_MESSAGE =~ /-draft$/
      when: never
    - if: '$CI_PIPELINE_SOURCE == "push"'

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

或者，所有 rules 都可以when: never，并带有最终 when: always rules 。符合when: never rules 的流水线不会运行，所有其他流水线类型运行：

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

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

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

`workflow:rules:variables`

你可以在 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"

当分支是默认分支时：

job1DEPLOY_VARIABLE是job1-deploy-production
job2DEPLOY_VARIABLE是deploy-production

当分支是feature时：

job1DEPLOY_VARIABLE是job1-default-deploy，IS_A_FEATURE 是true job2DEPLOY_VARIABLE是default-deploy，IS_A_FEATURE 是true

当分支是其它分支时：

job1DEPLOY_VARIABLE是job1-default-deploy job2DEPLOY_VARIABLE是default-deploy

workflow:rules 模板

我们为一些常见场景提供了 workflow: rules 设置的模板。这些模板有助于防止重复运行流水线。

Branch-Pipelines 模板可以使你的流水线为分支和 Tags 运行。

分支流水线状态显示在使用分支作为源的合并请求中。但是，这种流水线类型不支持合并请求流水线提供的任何功能，例如合并结果流水线或合并列车。此模板有意避免使用这些功能。

可以通过以下方式引用它：

include:
  - template: 'Workflows/Branch-Pipelines`.codechina-ci.yml`'

MergeRequest-Pipelines 模板可以使你的流水线针对默认分支、Tags 和所有类型的合并请求运行流水线。如果使用任何合并请求功能的流水线，请使用此模板。

可以通过以下方式引用它：

include:
  - template: 'Workflows/MergeRequest-Pipelines`.codechina-ci.yml`'

在分支流水线和合并请求流水线之间切换

要在创建合并请求后将流水线从分支流水线切换到合并请求流水线，在 .codechina-ci.yml 文件中添加 workflow: rules 部分。

如果同时使用两种流水线类型，则可能会同时运行重复的流水线。为防止重复运行流水线，请使用CI_OPEN_MERGE_REQUESTS变量。

以下示例适用于仅运行分支和合并请求流水线，但不为任何其他情况运行流水线的项目：

当分支没有打开合并请求时运行分支流水线
当分支的合并请求打开时运行合并请求流水线

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
      when: never
    - if: '$CI_COMMIT_BRANCH'

如果流水线由以下因素触发：

合并请求，运行合并请求流水线。例如，合并请求流水线可以通过推送到具有关联打开合并请求的分支来触发。
对分支的更改，但该分支的合并请求已打开，请不要运行分支流水线。
对分支的更改，但没有任何打开的合并请求，运行分支流水线。

你还可以向现有workflow部分添加 rules ，以便在创建合并请求时从分支流水线切换到合并请求流水线。

将此 rules 添加到该workflow部分的顶部，然后是已经存在的其他 rules ：

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - ...                # Previously defined workflow rules here

在分支上运行的流水线触发器有一个$CI_COMMIT_BRANCH 集合，可能会被类似的 rules 阻止。触发流水线的流水线源为trigger或pipeline，因此&& $CI_PIPELINE_SOURCE == "push"确保 rules 不会阻止触发流水线。

`include`

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

你还可以将模板文件存储在中央存储库中，并通过include将它们存储在项目中。

include要求外部 YAML 文件具有扩展名.yml或.yaml，否则不引用外部文件。

你不能在不同 YAML 文件之间通过使用 YAML 锚点的方式来 include .yaml。你只能引用同一文件中的锚点。要重用来自不同 YAML 文件的配置，请使用!reference 标签或 extends 关键字。

include 支持以下引用方法：

关键词	方法
`local`	引用本地项目存储库中的文件
`file`	引用来自不同项目存储库的文件
`remote`	引用来自远程 URL 的文件，必须可以公开访问。
`template`	引用模板

流水线启动时，.codechina-ci.yml会评估所有方法引用的文件配置。配置是一个及时的快照并储存在数据库中。.codechina-ci.yml在下一个流水线启动之前，不会同步对引用文件配置的任何更改。

这些include文件是：

与.codechina-ci.yml文件中的那些深度合并 = .codechina-ci.yml无论include关键字的位置如何，始终首先评估并与文件内容合并。

使用合并本地配置的 CI/CD 配置的方法来自定义和覆盖引用的配置。.codechina-ci.yml文件中的本地配置会覆盖引用的配置。

`include`变量

你可以在文件的部分中使用一些预定义的变量include .codechina-ci.yml：

include:
  project: '$CI_PROJECT_PATH'
  file: '.compliance-codechina-ci.yml'

`include:local`

使用include:local引用在同一个存储库中的.codechina-ci.yml文件。使用相对于根目录 (/) 的完整路径。

如果使用include:local，请确保.codechina-ci.yml文件和本地文件位于同一分支上。

你不能通过 Git 子模块路径包含本地文件。

所有嵌套的包含都在同一个项目的范围内执行，因此可以使用本地、项目、远程或模板引用。

例子：

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

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

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

使用本地引用而不是符号链接。

`include:local`带通配符文件路径

你可以在include:local中使用通配符路径（*和**）。

例子：

include: 'configs/*.yml'

当流水线运行时：

将.yml目录中的所有文件添加configs到流水线配置中。

不在.yml目录的子文件夹中添加文件configs。为此，请添加以下配置：

# This matches all `.yml` files in `configs` and any subfolder in it.
include: 'configs/**.yml'

# This matches all `.yml` files only in subfolders of `configs`.
include: 'configs/**/*.yml'

`include:file`

要引用来自另一个私有项目的文件，请使用include:file。你仅可以将include:file与include:project组合使用。使用相对于根目录 (/)的完整路径。

例如：

include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'

你还可以指定一个ref，如果不指定值，则 ref 默认为项目的 HEAD：

include:
  - project: 'my-group/my-project'
    ref: main
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: v1.0.0
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b  # Git SHA
    file: '/templates/.gitlab-ci-template.yml'

所有嵌套的引用都在目标项目的范围内执行。你可以使用本地（相对于目标项目）、项目、远程或模板引用。

一个项目中的多个文件

你可以引用来自同一项目的多个文件：

include:
  - project: 'my-group/my-project'
    ref: main
    file:
      - '/templates/.builds.yml'
      - '/templates/.tests.yml'

`include:remote`

include:remote与完整 URL 一起使用，可以引用来自不同位置的文件。因为不支持远程 URL 中的身份验证，远程文件必须可通过 HTTP/HTTPS GET请求公开访问。例如：

include:
  - remote: 'https://codechina.csdn.net/example-project/-/raw/main/.codechina-ci.yml'

所有嵌套引用都以公共用户身份在没有上下文的情况下执行，因此你只能使用include公共项目或模板。

`include:template`

使用include:template 引用 .codechina-ci.yml模板。

例如：

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

多个include:template文件：

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

所有嵌套引用仅在用户许可的情况下执行，因此可以使用项目、远程或模板引用。

嵌套引用

使用嵌套引用来组成一组引用。最多可以有 100 个引用，但不能有重复的引用，解析所有文件的时间限制为 30 秒。

关键字详情

接下来，我们介绍如何通过关键字来配置 CI/CD 流水线。

`image`

使用image指定用于流水线任务的 Docker 镜像。

用法示例，请参见.codechina-ci.yml文件中的定义 image 。
详细使用信息，参考 Docker 集成文档。

`image:name`

一个扩展 Docker 配置选项。

有关更多信息，请参阅的可用设置image。

`image:entrypoint`

一个扩展 Docker 配置选项。

有关更多信息，请参阅的可用设置image。

`services`

使用services指定 Docker 镜像，链接到指定的基本镜像。

用法示例，请参见.codechina-ci.yml文件中的定义services。
详细使用信息，参考Docker集成文档。
示例服务，请参阅GitLab CI/CD 服务。

`services:name`

一个扩展 Docker 配置选项。

`services:alias`

一个扩展 Docker 配置选项。

`services:entrypoint`

一个扩展 Docker 配置选项。

`services:command`

一个扩展 Docker 配置选项。

`script`

使用script为 Runner 指定要执行的 shell 脚本。

除触发器流水线任务外的所有流水线任务都需要一个script关键字。

例如：

job:
  script: "bundle exec rspec"

你可以使用 YAML 锚点的 script.

script关键字也可以包含一组命令：

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

有时，script命令必须用单引号或双引号括起来。例如，包含冒号 ( :) 的命令必须用单引号 ( ')括起来。YAML 解析器需要将文本解释为字符串而不是“键：值”对。

例如，此脚本中使用了冒号：

job:
  script:
    - curl --request POST --header 'Content-Type: application/json' "https://gitlab/api/v4/projects"

要被视为有效的 YAML，你必须将整个命令用单引号括起来。如果命令已使用单引号，则应将它们更改为双引号 ( ")：

job:
  script:
    - 'curl --request POST --header "Content-Type: application/json" "https://gitlab/api/v4/projects"'

你可以使用CI Lint工具验证语法是否有效。

使用这些字符时也要小心：

{, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `

如果任何脚本命令返回零以外的退出代码，则流水线任务失败并且不会执行进一步的命令。将退出代码存储在变量中以避免这种行为：

job:
  script:
    - false || exit_code=$?
    - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;

`before_script`

使用before_script定义应在每次流水线任务之前运行的命令组，但需要在artifacts恢复后。

你在 before_script 其中指定的脚本与你在 main script 中指定的任何脚本连接在一起。组合后的脚本在单个 shell 中一起执行。

before_script如果在流水线任务中定义它，则可以覆盖全局定义：

default:
  before_script:
    - echo "Execute this script in all jobs that don't already have a before_script section."

job1:
  script:
    - echo "This script executes after the global before_script."

job:
  before_script:
    - echo "Execute this script instead of the global before_script."
  script:
    - echo "This script executes after the job's `before_script`"

可以在before_script中使用 YAML 锚点。

`after_script`

使用after_script定义每个流水线任务后运行命令组，包括失败的流水线任务。

如果流水线任务超时或被取消，则after_script不会执行。

你指定的after_script脚本在新 shell 中执行，与任何 before_script或script脚本分开。通过这样：

将当前流水线任务目录设置回默认值。
无法访问 before_script 或 script 中定义的脚本所做的更改，包括：
- script脚本中导出的命令别名和变量。
- 工作树之外的更改（取决于运行程序执行程序），例如由 before_script 或 script 脚本安装的软件。
有一个单独的超时，它被硬编码为 5 分钟。
不影响流水线任务的退出代码。如果该script部分成功并且 after_script超时或失败，则流水线任务将退出并显示代码0( Job Succeeded)。

default:
  after_script:
    - echo "Execute this script in all jobs that don't already have an after_script section."

job1:
  script:
    - echo "This script executes first. When it completes, the global after_script executes."

job:
  script:
    - echo "This script executes first. When it completes, the job's `after_script` executes."
  after_script:
    - echo "Execute this script instead of the global after_script."

可以在after_script中使用 YAML 锚点。

`Script` 语法

你可以在script中使用语法来：

将长命令拆分为多行命令。
使用颜色代码使流水线任务日志更易于查看。
创建自定义可折叠部分以简化流水线任务日志输出。

`stage`

使用stage定义在哪一个阶段运行流水线任务。流水线任务在同一 stage 可以并行执行（某些条件下）。

没有stage条目的流水线任务默认使用test阶段。如果没有在流水线中定义stages ，则可以使用 5 个默认阶段，它们按以下顺序执行：

.pre
build
test
deploy
.post

例如：

stages:
  - build
  - test
  - deploy

job 0:
  stage: .pre
  script: make something useful before build stage

job 1:
  stage: build
  script: make build dependencies

job 2:
  stage: build
  script: make build artifacts

job 3:
  stage: test
  script: make test

job 4:
  stage: deploy
  script: make deploy

job 5:
  stage: .post
  script: make something useful at the end of pipeline

使用你自己的 Runner

当你使用自建的 Runner 时，默认情况下每个 Runner 一次仅运行一项流水线任务。如果流水线任务在不同的 Runner 上运行，它们可以并行运行。

如果你只有一个 Runner ，并且 Runner 的 concurrent 设置大于 1，则流水线任务可以并行运行。

`.pre` 和 `.post`

将pre和post用于需要在流水线中首先或最后运行的流水线任务。

.pre 保证始终是流水线中的第一阶段。
.post 保证始终是流水线中的最后阶段。

用户定义的阶段将在 .pre 之后和 .post 之前执行。

你必须在.pre或.post以外的至少一个阶段有一个流水线任务。

你不能更改 .pre 和 .post 的顺序，即使你在.codechina-ci.yml文件中不按顺序定义它们。例如，以下配置是等效的：

stages:
  - .pre
  - a
  - b
  - .post

stages:
  - a
  - .pre
  - b
  - .post

stages:
  - a
  - b

`extends`

使用 extends 重用配置部分。它是YAML 锚点的替代品，并且更加灵活、有更强的可读性。你可以使用extends从引用的配置文件中重用配置。

在以下示例中，rspec 流水线任务使用 .tests 模板流水线任务中的配置。系统会：

根据键执行反向深度合并。
将 .tests 内容与 rspec 流水线任务合并。
不合并键的值。

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

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

结果 rspec 的流水线任务是：

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

.tests 在这个例子中是一个隐藏流水线任务，但也可以从常规流水线任务扩展配置。

extends 支持多级继承。你应该避免使用三个以上的级别，但你仍可以使用多达 11 个级别。以下示例具有两个继承级别：

.tests:
  only:
    - pushes

.rspec:
  extends: .tests
  script: rake rspec

rspec 1:
  variables:
    RSPEC_SUITE: '1'
  extends: .rspec

rspec 2:
  variables:
    RSPEC_SUITE: '2'
  extends: .rspec

spinach:
  extends: .tests
  script: rake spinach

你也可以为 extends 设置多个父级。

合并请求详情

你可以将 extends 用于合并散列但不能用于数组。用于合并的算法是“最接近的范围获胜”，因此来自最后一个成员的键值总是覆盖其他级别上定义的任何内容。例如：

.only-important:
  variables:
    URL: "http://my-url.internal"
    IMPORTANT_VAR: "the details"
  only:
    - main
    - stable
  tags:
    - production
  script:
    - echo "Hello world!"

.in-docker:
  variables:
    URL: "http://docker-url.internal"
  tags:
    - docker
  image: alpine

rspec:
  variables:
    GITLAB: "is-awesome"
  extends:
    - .only-important
    - .in-docker
  script:
    - rake rspec

结果 rspec 的流水线任务是：

rspec:
  variables:
    URL: "http://docker-url.internal"
    IMPORTANT_VAR: "the details"
    GITLAB: "is-awesome"
  only:
    - main
    - stable
  tags:
    - docker
  image: alpine
  script:
    - rake rspec

在这个例子中：

这些variables部分合并，但URL: "http://docker-url.internal" 覆盖 URL: "http://my-url.internal"
tags: ['docker'] 覆盖 tags: ['production']
script 不合并，但 script: ['rake rspec'] 覆盖 script: ['echo "Hello world!"']。你可以使用YAML 锚点来合并数组。

`extends` 和 `include` 一起使用

要重用来自不同配置文件的配置，你可以将 extends 和 include 结合起来使用。

在以下示例中，script 在included.yml文件中定义了a 。然后，在.codechina-ci.yml文件中，extends引用了以下script内容：

included.yml：
```
.template:
  script:
    - echo Hello!
```

. codechina-ci.yml:

include: included.yml

useTemplate:
  image: alpine
  extends: .template

`rules`

rules 用于在流水线中添加或排除流水线任务。

rules 按顺序评估，直到第一次匹配。找到匹配项后，会将该流水线任务包含在流水线中或从流水线中排除，取决于具体的配置。流水线任务还可以添加某些属性。

rules 替换 only/except ，并且它们不能在同一个流水线任务中一起使用。如果你在一个流水线任务配置为使用这两个关键字，则 linter 会返回 key may not be used with rules 的错误提示。

Rules attributes

rules 中你可以使用的流水线任务属性是：

when: 如果未定义，则默认为 when: on_success。
- 如果用作when: delayed，start_in也是必需的。
allow_failure: 如果未定义，则默认为 allow_failure: false。
variables: 如果未定义，则使用别处定义的变量。

如果 rules 评估为真，并且 when 具有除 never 之外的任何值，则流水线任务将包含在流水线中。

例如：

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: delayed
      start_in: '3 hours'
      allow_failure: true

`Rules` 条款

可用的Rules 条款有：

条款	描述
`if`	通过评估`if`语句向流水线中添加或排除流水线任务。类似于 `only:variables`
`changes`	根据更改的文件从流水线中添加或排除流水线任务。与 `only:changes` 相同
`exists`	根据特定文件的存在与否向流水线中添加或排除流水线任务

rules 按顺序进行评估，直到找到匹配项。如果找到匹配项，则会检查属性以查看是否应将流水线任务添加到流水线中。如果未定义属性，则默认值为：

when: on_success
allow_failure: false

流水线任务被添加到流水线中：

如果 rules 匹配并且具有 when: on_success， when: delayed 或 when: always
如果没有 rules 匹配，但最后一个子句是 when: on_success, when: delayed 或 when: always（没有 rules ）

流水线任务未添加到流水线中：

如果没有 rules 匹配，并且没有独立的 when: on_success，when: delayed 或 when: always
如果 rules 匹配，并且具有 when: never 作为属性

以下示例用于if严格限制流水线任务何时运行：

job:
  script: echo "Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: manual
      allow_failure: true
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

如果流水线用于合并请求，则第一个规则匹配，并且流水线任务将添加到合并请求流水线中，其属性为：
- when: manual （手工流水线任务）
- allow_failure: true （即使未运行手动流水线任务，流水线也会继续运行）
如果流水线不是用于合并请求，则第一条规则不匹配，并评估第二条规则。
如果流水线是计划流水线，则第二条规则匹配，并将流水线任务添加到计划流水线。没有定义属性，因此添加了：
- when: on_success （默认）
- allow_failure: false （默认）
在所有其他情况下，没有规则匹配，因此不会将流水线任务添加到任何其他流水线。

或者，你可以定义一组在少数情况下排除流水线任务的 rules，但在所有其他情况下运行它们：

job:
  script: echo "Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: never
    - when: on_success

如果流水线用于合并请求，则不会将流水线任务添加到流水线中。
如果流水线是计划流水线，则不会将流水线任务添加到流水线中。
在所有其他情况下，流水线任务将添加到流水线中，带有 when: on_success。

如果你使用 when: 条款作为最终规则（不包括 when: never），则可能会同时启动两个流水线。推送流水线和合并请求流水线都可以由同一事件触发（推送到源分支以获取开放合并请求）。

避免重复的流水线

如果流水线任务使用rules，则单个操作（例如将提交推送到分支）可以触发多个流水线。你不必为多种类型的流水线显式配置规则来意外触发它们。

例如：

job:
  script: echo "This job creates double pipelines!"
  rules:
    - if: '$CUSTOM_VARIABLE == "false"'
      when: never
    - when: always

当$CUSTOM_VARIABLE 是 false时此流水线任务不运行，但它在所有其他流水线中运行，包括推（分支）和合并请求两个流水线。使用此配置，每次推送到开放合并请求的源分支都会导致重复的流水线。

为避免重复流水线，你可以：

使用 CI_OPEN_MERGE_REQUESTS CI/CD 变量 workflow:rules 在分支和合并请求流水线之间进行切换，而不产生重复的流水线。你还可以在单个流水线任务规则中使用此变量。
使用 workflow 指定只在分支流水线或只在合并请求流水线中运行。

重写规则以仅在非常特定的情况下运行流水线任务，并避免最终的 when: 规则：

job:
  script: echo "This job does NOT create double pipelines!"
  rules:
    - if: '$CUSTOM_VARIABLE == "true" && $CI_PIPELINE_SOURCE == "merge_request_event"'

你还可以通过更改流水线任务规则来避免重复流水线，以避免推送（分支）流水线或合并请求流水线。但是，如果你使用没有规则 workflow: rules 的 - when: always，系统仍会显示流水线警告。

例如，以下不会触发双流水线，但不推荐没有workflow: rules：

job:
  script: echo "This job does NOT create double pipelines!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push"'
      when: never
    - when: always

你不应在同一流水线任务中同时包含推送和合并请求流水线的 workflow:rules，以免防止重复流水线：

job:
  script: echo "This job creates double pipelines!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

此外，不要将同一流水线中的 only/except 流水线任务与 rules 流水线任务混合在一起。它可能不会引起 YAML 错误，但不同的默认行为的 only/except 和 rules 可能会导致一些难以解决的问题：

job-with-no-rules:
  script: echo "This job runs in branch pipelines."

job-with-rules:
  script: echo "This job runs in merge request pipelines."
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

对于推送到分支的每个更改，都会运行重复的流水线。一个分支流水线运行单个流水线任务 ( job-with-no-rules)，一个合并请求流水线运行另一个流水线任务 ( job-with-rules)。没有规则的流水线任务默认为 except: merge_requests，因此 job-with-no-rules 在除合并请求之外的所有情况下都会运行。

`rules:if`

使用 rules:if 条款指定何时向流水线添加流水线任务：

如果if语句为真，则将流水线任务添加到流水线中。
如果某个if语句为真，但与 when: never 结合使用，则不会将流水线任务添加到流水线中。
如果没有任何if语句为真，则不会将流水线任务添加到流水线中。

rules:if 与 only:variables 略有不同，它的每个规则只接受一个表达式字符串而不是数组。任何一组要计算的表达式都可以通过使用 && 或 || ，以及变量匹配运算符 (==, !=, =~ 和 !~) 连成一个表达式。

与 script 中的变量不同，规则表达式中的变量始终格式为 $VARIABLE。

if: 条款根据预定义 CI/CD 变量或自定义 CI/CD 变量的值进行评估。

例如：

job:
  script: echo "Hello, Rules!"
  rules:
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
      when: always
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/'
      when: manual
      allow_failure: true
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'  # Checking for the presence of a variable is possible

有关确定 when 流水线任务的逻辑的一些详细信息：

如果提供的规则都不匹配，则流水线任务将设置为 when: never 并且不包含在流水线中。
没有任何条款的规则，例如 when 或 allow_failure 规则没有 if 或者没有 changes，总是匹配，并且总是在符合时使用。
如果规则匹配到并且未定义 when，则使用 when 规则定义的流水线任务，，且未定义的情况下默认为 on_success。
你可以为每个规则定义一次 when，也可以在流水线任务级别定义一次，这将适用于所有规则。你不能在流水线任务级别 when 与规则 when 混合使用。

`rules` 的通用 `if` 条款

对于类似于 only/except 关键字的行为，你可以检查 $CI_PIPELINE_SOURCE 变量的值：

值	描述
`api`	由 pipelines API 触发的流水线
`chat`	使用 GitLab ChatOps 命令创建的流水线
`external`	当你使用 GitLab 以外的 CI 服务
`external_pull_request_event`	在 GitHub 上创建或更新外部拉取请求时
`merge_request_event`	对于在创建或更新合并请求时创建的流水线。需要启用合并请求流水线、合并结果流水线和 `merge trains`
`parent_pipeline`	对于由带有 `rules` 的父/子流水线触发的流水线。在子流水线配置中使用此流水线源，以便它可以由父流水线触发
`pipeline`	对于通过使用带有`CI_JOB_TOKEN`的API创建的多项目流水线，或 `trigger` 关键字
`push`	对于由“git push”事件触发的流水线，包括分支和标签
`schedule`	计划流水线
`trigger`	对于使用 `trigger token` 创建的流水线
`web`	对于使用 UI 中的流水线按钮创建的流水线，来自项目的 Devops > 流水线部分
`webide`	对于使用 `WebIDE` 创建的流水线

以下示例在计划的流水线或推送中将流水线任务作为手动流水线任务运行流水线（到分支或标签），带有 when: on_success（默认）。它不会将流水线任务添加到任何其他流水线类型。

job:
  script: echo "Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: manual
      allow_failure: true
    - if: '$CI_PIPELINE_SOURCE == "push"'

以下示例中当 when: on_success 时将在合并请求流水线和计划流水线运行流水线任务。它不会在任何其他流水线类型中运行。

job:
  script: echo "Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

if 条款的其他常用变量：

if: $CI_COMMIT_TAG：如果为标签推送更改。
if: $CI_COMMIT_BRANCH：如果更改被推送到任何分支。
if: '$CI_COMMIT_BRANCH == "main"'：如果更改被推送到 main。
if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'：如果更改被推送到默认分支。当你想在多个相同的配置中使用具有不同默认分支的项目。
if: '$CI_COMMIT_BRANCH =~ /regex-expression/'：如果提交分支匹配正则表达式。
if: '$CUSTOM_VARIABLE !~ /regex-expression/': 如果自定义变量 CUSTOM_VARIABLE 不匹配正则表达式。
if: '$CUSTOM_VARIABLE == "value1"'：如果自定义变量 CUSTOM_VARIABLE 值正是value1。

`rules:changes`

使用 rules:changes 当改特定文件时将流水线任务添加到流水线。

rules: changes 的工作方式与 only: changes 和 except: changes 相同。它接受一组路径。你应该只对分支使用 rules: changes 流水线或合并请求流水线。例如，通常对合并请求流水线使用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 用于分支流水线而不是合并请求流水线，将之前示例中的 if: 子句更改为：

rules:
  - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH

要实现类似于 except:changes 的规则，使用 when: never。

你可以将 rules: changes 与其他流水线类型一起使用，但不推荐使用。因为当没有 Git push 事件时，rules: changes 总是评估为 true。标记流水线、计划流水线等没有有 Git push 事件与他们有关。rules: changes 流水线任务始终添加到这些流水线中，如果没有 if: 语句将流水线任务限制为分支或合并请求流水线的话。

`rules:changes` 中的变量

你可以在 rules:changes 表达式中使用 CI/CD 变量来确定何时向流水线添加流水线任务：

docker build:
  variables:
    DOCKERFILES_DIR: 'path/to/files/'
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - changes:
        - $DOCKERFILES_DIR/*

你可以将 $ 字符用于变量和路径。例如，如果 $DOCKERFILES_DIR 变量存在，它的值被使用。如果不存在，则 $ 被解释为路径的一部分。

`rules:exists`

当存储库中存在某些文件时，使用 exists 来运行流水线任务。你可以使用一组路径。

在以下示例中，如果存储库中的任何位置存在 Dockerfile，job 就会运行：

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

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

你可以使用 glob 的模式在存储库中匹配任何目录中的多个文件：

job:
  script: bundle exec rspec
  rules:
    - exists:
        - spec/**.rb

Glob 模式用 Ruby 解释 File.fnmatch 带有标志 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB。

出于性能原因，最多匹配 10,000 个 exists 模式。在第 10,000 次检查之后，带有 glob 的规则将始终匹配。

`rules:allow_failure`

你可以在 rules: 中使用 allow_failure: true 来允许流水线任务失败，或等待一个手动流水线任务的操作，而不停止流水线本身。所有使用 rules: 的流水线任务在你没有定义 allow_failure:的情况下默认为 allow_failure: false。

规则级别的 rules:allow_failure 选项覆盖流水线任务级别 allow_failure 选项，仅在特定规则触发流水线任务后进行。

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

在此示例中，如果第一条规则匹配，则流水线任务具有 when: manual 和 allow_failure: true。

`rules:variables`

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

复杂规则条款

要将 if 、 changes 和 exists 条款用 AND 连接起来，并用在同一条规则中。

在以下示例中：

如果 Dockerfile 文件或 /docker/scripts 中的任何文件发生了变化，并且 $VAR == "string value"，则流水线任务手动运行
否则，流水线任务不包含在流水线中。

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: '$VAR == "string value"'
      changes:  # Include the job and set to when:manual if any of the follow paths match a modified file.
        - Dockerfile
        - docker/scripts/*
      when: manual
      # - "when: never" would be redundant here. It is implied any time rules are listed.

诸如 branches 或 refs 之类的关键字可用于 only/except，但在 rules 中不可用。

你可以使用括号 [] 和 && 和 || 来构建更复杂的变量表达式。

job1:
  script:
    - echo This rule uses parentheses.
  rules:
    if: ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE

`only` / `except`

你可以使用 only 和 except 来控制何时向流水线添加流水线任务。

使用 only 来定义流水线任务何时运行。
使用 except 定义流水线任务何时不运行。

四个关键字可以与 only 和 except 一起使用：

refs
变量
changes
kubernetes

`only:refs` / `except:refs`

使用 only:refs 和 except:refs 关键字来控制何时将流水线任务添加到基于分支名称或流水线类型的流水线。

关键字类型：流水线任务关键字。你只能将其用作流水线任务的一部分。

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

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

以下关键词：

关键词	说明
`api`	对于由 pipelines API 触发的流水线
`branches`	当流水线的 Git 引用是分支时
`chat`	对于使用 ChatOps命令创建的流水线
`external`	当你使用 GitLab 以外的 CI 服务时
`external_pull_requests`	在 GitHub 上创建或更新外部拉取请求时
`merge_request`	对于在创建或更新合并请求时创建的流水线。启用合并请求流水线、合并的结果流水线和 `merge trains`
`pipelines`	对于通过使用带有`CI_JOB_TOKEN`的API创建的多项目流水线，或 `trigger` 关键字
`push`	对于由“git push”事件触发的流水线，包括分支和标签
`schedules`	计划流水线
`tags`	当流水线的 Git 引用是标签时
`triggers`	对于使用 `trigger token` 创建的流水线
`web`	对于使用 UI 中的流水线按钮创建的流水线，来自项目的 DevOps > 流水线部分

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。比如下面两个job的配置是一样的行为：

job1:
  script: echo
  only:
    - branches

job2:
  script: echo
  only:
    refs:
      - branches

如果流水线任务不使用 only、except 或 rules，则 only 默认设置为 branches 和tag。

例如，job1 和 job2 是等价的：
```
job1:
  script: echo 'test'

job2:
  script: echo 'test'
  only:
  - branches
  - tags
```

`only:variables` / `except:variables`

使用 only:variables 或 except:variables 关键字来控制何时添加流水线任务到流水线，基于 CI/CD 变量的状态。

关键字类型：流水线任务关键字。你只能将其用作流水线任务的一部分。

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

only:variables 示例：

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

`only:changes` / `except:changes`

当 Git 推送事件修改文件时，使用 changes 关键字和 only 来运行一个流水线任务，或者使用 except 来跳过一个流水线任务。

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

分支
external_pull_requests
merge_requests

关键字类型：流水线任务关键字。你只能将其用作流水线任务的一部分。

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

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

更多细节：

如果你使用除 branches、external_pull_requests 或 merge_requests 以外的引用，changes 无法确定给定文件是新文件还是旧文件，并且总是返回 true。
如果你将 only: changes 与其他引用一起使用，流水线任务将忽略更改并始终运行。
如果你将 except: changes 与其他引用一起使用，流水线任务将忽略更改并且

`only:kubernetes` / `except:kubernetes`

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

关键字类型：特定于流水线任务。你只能将其用作流水线任务的一部分。

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

only:kubernetes 示例：

deploy:
  only:
    kubernetes: active

在此示例中，deploy 流水线任务仅在 Kubernetes 服务处于活动状态时运行在项目中。

`needs`

使用 needs: 来乱序执行流水线任务。流水线任务之间的关系可使用 needs 可视化为有向无环图。

你可以忽略阶段排序并运行一些流水线任务，而无需等待其他流水线任务完成。多个阶段的流水线任务可以同时运行。

以下示例创建四个执行路径：

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。

linux:build:
  stage: build

mac:build:
  stage: build

lint:
  stage: test
  needs: []

linux:rspec:
  stage: test
  needs: ["linux:build"]

linux:rubocop:
  stage: test
  needs: ["linux:build"]

mac:rspec:
  stage: test
  needs: ["mac:build"]

mac:rubocop:
  stage: test
  needs: ["mac:build"]

production:
  stage: deploy

要求和限制

在 GitLab 13.9 及更早版本中，如果 needs: 指的是因 only、except 或 rules 等可能不会添加到的流水线任务，则流水线可能无法创建。
needs: 数组中单个流水线任务可以需要的最大流水线任务数是有限的，限制是：50。
如果 needs: 是指使用 parallel 关键字的流水线任务，这取决于并行创建的所有流水线任务，而不仅仅是一项流水线任务。它也下载默认情况下来自所有并行流水线任务的 artifacts。如果 artifacts 有相同的名称，它们会相互覆盖，并且只保存最后下载的一个。
needs: 类似于 dependencies:，因为它必须使用先前阶段的流水线任务，这意味着不可能创建循环依赖项。根据流水线任务当前阶段也不可能。
必须为所有有关键字 needs: 或被其引用的流水线任务明确定义阶段。

使用 `needs` 下载 `artifacts`

当流水线任务使用 needs 时，默认情况下它不再下载前一阶段的所有 artifacts，因为具有 medds 的流水线任务可以在早期阶段完成之前开始。当存在 needs 时，你只能从 needs: 配置中列出的流水线任务下载 artifacts。

使用 artifacts: true（默认值）或 artifacts: false 在出现在使用 needs 的流水线任务中来控制何时下载 artifacts。

在以下示例中，rspec 流水线任务下载了 build_job 的 artifacts，但是rubocop 流水线任务不会：

build_job:
  stage: build
  artifacts:
    paths:
      - binaries/

rspec:
  stage: test
  needs:
    - job: build_job
      artifacts: true

rubocop:
  stage: test
  needs:
    - job: build_job
      artifacts: false

在以下示例中，rspec 流水线任务从所有三个 build_jobs 中下载 artifacts。其中 artifacts 设置为：

对 build_job_1 设置为 true。
对于 build_job_2 和 build_job_3，默认为 true。

rspec:
  needs:
    - job: build_job_1
      artifacts: true
    - job: build_job_2
    - build_job_3

`needs` 跨项目下载 `artifacts`

流水线中使用 needs 从最多五个流水线任务下载 artifacts：

在同一项目中的其他 ref
在不同的项目、组和命名空间中

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

build_job 从 group/project-name 项目的 main 分支上最新成功的 build-1 流水线任务下载 artifacts。如果项目在相同的组或命名空间，你可以从 project: 关键字中省略它们。例如， project: group/project-name 或 project: project-name。

运行流水线的用户必须至少具有对组或项目的Reporter访问权限，或者组/项目是公开可见的。

同一项目中流水线间的 `artifacts` 下载

使用 needs 从当前项目中的不同流水线下载 artifacts。将 project 关键字设置为当前项目的名称，并指定一个 ref。

在以下示例中，build_job 从 ref 为 other-ref 的 build-1 流水线任务下载最新成功的 artifacts：

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: group/same-project-name
      job: build-1
      ref: other-ref
      artifacts: true

project:、job: 和 ref 也支持 CI/CD 变量形式的参数。

例如：

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

你无法从 parallel: 中运行的流水线任务下载 artifacts。

要在父子流水线之间下载 artifacts，使用 needs:pipeline。

你不应从相同的 ref 下正在运行的流水线下载 artifacts，在同一个 ref 上运行的流水线可能会覆盖 artifacts。

`artifacts` 下载到子流水线

子流水线可以从它的父流水线或同一父流水线中的另一个子流水线流水线任务中下载 artifacts。

例如，以下是一个会创建一些 artifacts 的父流水线：

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

子流水线中的流水线任务可以从父流水线：create-artifact 流水线任务中下载 artifacts：

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

pipeline 接受一个流水线 ID，它必须是一个存在于给定流水线的相同父流水线层次结构中的流水线。

pipeline 不接受当前的流水线 ID ($CI_PIPELINE_ID)。如果要从当前流水线中的流水线任务下载 artifacts，请使用 needs 的基本形式。

可选 `needs`

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

使用 rules、only 或 except 的流水线任务可能并不总是存在于流水线中。当流水线启动时，在运行之前它会检查 needs 的关系。如果没有设置optional: true，且需要的关系指向不存在的流水线任务时会阻止流水线启动并导致流水线产生一个类似如下错误：

'job1' job needs 'job2' job, but it was not added to the pipeline

在下面这个例子中：

当分支为默认分支时，流水线中存在 build 流水线任务，rspec 流水线任务在开始之前等待它完成。
当分支不是默认分支时，流水线中不存在 build 流水线任务。rspec 流水线任务立即运行（类似于 needs: []），因为它的 needs 与 build 流水线任务的关系是可选的。

build:
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

rspec:
  stage: test
  needs:
    - job: build
      optional: true

`tags`

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

当你注册 Runner 时，你可以指定 Runner 的 tag，比如ruby、postgres、development等。

在以下示例中，流水线任务由同时定义了 ruby 和 postgres tag 的 Runner 运行。

job:
  tags:
    - ruby
    - postgres

你可以使用 tag 在不同平台上运行不同的流水线任务。比如，如果你有一个带有 osx 标签的 OS X Runner 和一个带有 windows 标签的 Windows Runner，你可以通过以下设置在每个平台上运行一个流水线任务：

windows job:
  stage:
    - build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage:
    - build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"

`allow_failure`

当你想让流水线任务失败而不影响 CI 组合的其余部分时，请使用 allow_failure。它的默认值为 false，manual 使用 when: manual 语法时除外。

在使用 rules: 的流水线任务中，所有流水线任务默认为 allow_failure: false，包括 when: manual 流水线任务。

当 allow_failure 设置为 true 并且流水线任务失败时，流水线任务会在 UI 中显示橙色警告。但是，流水线的逻辑流仍会将流水线任务视为成功/通过，并且该流水线不会被 block。

假设所有其他流水线任务都成功，流水线任务的 stage 及其流水线显示相同的橙色警告。但是，与之关联的提交被标记为 passed，并且没有警告提示。

在以下示例中，job1 和 job2 并行运行，如果 job1 失败，它不会停止下一个阶段的运行，因为它被标记为 allow_failure: true:

job1:
  stage: test
  script:
    - execute_script_that_will_fail
  allow_failure: true

job2:
  stage: test
  script:
    - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
    - deploy_to_staging

`allow_failure:exit_codes`

使用 allow_failure:exit_codes 动态控制是否应该允许流水线任务失败。你可以列出哪些退出代码不被视为失败。对于任何其他退出代码，流水线任务失败：

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（默认）- 只有在早期阶段的所有流水线任务都成功时才执行流水线任务，或者当它们设置了 allow_failure: true 时，总是视作成功的。
on_failure - 仅在较早阶段的至少一项流水线任务失败时才执行流水线任务。
always - 无论早期阶段的流水线任务状态如何，都执行流水线任务。
manual - 手动执行流水线任务。
delayed - 延迟流水线任务的执行指定的持续时间。
never：
- 使用流水线任务 rules，不执行流水线任务。
- 使用 workflow:rules，不运行流水线。

在以下示例中，脚本代码：

只有当 build_job 失败时才执行 cleanup_build_job。
始终执行 cleanup_job 作为流水线的最后一步，不管成功或失败。
在 UI 中手动运行时执行 deploy_job。

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

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

`when:manual`

手动流水线任务是一种不会自动执行的流水线任务，它必须由用户启动。你可能希望将手动流水线任务用于部署到生产之类的事情。

要实现一个手动的流水线，请将 when: manual 添加到其配置中。

流水线启动时，手动流水线任务显示为已跳过且不会自动运行。它们可以从流水线、流水线任务、环境和部署视图中启动执行。

手动流水线任务可以是可选的或阻塞的：

可选：手动流水线任务默认设置为 `allow_failure: true 并且被认为是可选的。可选手工流水线任务的状态并不影响整体的流水线状态。即使所有手动流水线任务都失败，流水线也可以成功运行。
阻塞：要将手动流水线任务设置为阻塞，请将 allow_failure: false 添加到其配置中。阻塞的手动流水线任务会在其被定义的下一阶段停止流水线的进一步执行。要让流水线继续运行，请单击阻塞手动流水线任务上的 {play} 按钮。

项目中设置了流水线成功时合并的合并请求在有流水线阻塞的情况下无法合并。阻塞的流水线显示阻塞的状态。

当你使用 rules: 时，allow_failure 的值默认为 false，包括手动流水线任务。

要触发手动流水线任务，用户必须具有合并到指定分支的权限。你可以使用保护分支来更限制未经授权的用户运行保护手动部署。

`when:delayed`

使用 when: delay 在等待期后执行脚本，或者如果你想避免流水线任务立即进入 pending 状态。

你可以使用 start_in 关键字设置时间范围。start_in 的值是以秒为单位的时间范围，除非提供了时间单位。start_in 必须小于或等于 1 周。有效值的示例包括：

'5'
5 seconds
30 minutes
1 day
1 week

Delay 设置的时间不计算在流水线用量中，但默认流水线超时时间为60分钟，建议不要设置过长，否则会因为超时导致流水线的失败。

当阶段包含延迟流水线任务时，流水线在延迟流水线任务完成之前不会进行。你可以使用此关键字在不同阶段之间插入延迟。

延迟流水线任务的计时器在前一阶段完成后立即启动。与其他类型的流水线任务类似，除非前一阶段通过，否则延迟流水线任务的计时器不会启动。

以下示例创建了一个名为 timed rollout 10% 的流水线任务，该流水线任务在前一阶段完成 30 分钟后执行：

timed rollout 10%:
  stage: deploy
  script: echo 'Rolling out 10% ...'
  when: delayed
  start_in: 30 minutes

要停止延迟流水线任务的活动计时器，请单击 {time-out} (Unschedule) 按钮。之后，将无法再安排此流水线任务自动运行。但是，你可以手动执行流水线任务。

要立即开始延迟流水线任务，请单击 play 按钮。很快，Runner 将接手并开始工作。

`environment`

使用 environment 定义流水线任务部署到的环境。

例如：

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

你可以使用以下方法为 environment 关键字进行赋值：

纯文本，如 production。
变量，包括 CI/CD 变量、预定义、安全或变量，在.codechina-ci.yml 文件中定义。

你不能使用在 script 部分中定义的变量。

如果你指定了一个 environment 且不存在具有该名称的环境，就会新建这个环境。

`environment:name`

为 environment 设置名称。例如：

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

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

你可以使用以下命令为 name 关键字进行赋值：

纯文本，如staging。
变量，包括在.codechina-ci.yml 文件中定义的 CI/CD 变量、预定义、安全或变量。

你不能使用在 script 部分中定义的变量。

环境 name 可以包含：

Letters
Digits
Spaces
-
_
/
$
{
}

`environment:url`

为 environment 设置 URL。例如：

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

流水线任务完成后，你可以使用合并请求中的按钮访问 URL，环境或部署页面。

你可以使用以下方法为 url 关键字进行赋值：

纯文本，如https://prod.example.com。
变量，包括在.codechina-ci.yml 文件中定义 CI/CD 变量、预定义、安全或变量。

你不能使用在 script 部分中定义的变量。

`environment:on_stop`

关闭（停止）环境可以在 environment 下定义使用 on_stop 关键字来实现。它声明了一个不同的流水线任务来关闭环境。

阅读 environment:action 部分的示例。

`environment:action`

使用 action 关键字来指定准备、启动或停止环境的流水线任务。

| 值 | 说明 | |-----------|------------------------------------ -------------------------------------------------- -------------------------------------------------- ---------------| | start | 默认值。表示流水线任务启动环境。部署是在流水线任务启动后创建的 | | prepare | 表示流水线任务只准备环境。它不会触发部署 | | stop | 表示流水线任务停止部署。请参阅下面的示例 |

举个例子：

review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review/$CI_COMMIT_REF_NAME
    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_NAME
    action: stop

在上面的例子中，review_app 流水线任务部署到 review 环境。在 on_stop 下列出了一个新的 stop_review_app 流水线任务。在 review_app 流水线任务完成后，它会基于 when 下定义的内容触发 stop_review_app 流水线任务。在这个例子中，它被设置为 manual，所以它需要一个 manual action 并从 UI 中手动运行。

在示例中，GIT_STRATEGY 设置为 none。如果 stop_review_app 流水线任务是自动触发，删除分支后，运行程序不会尝试检查代码。

该示例还覆盖了全局变量。如果你的 stop environment 流水线任务取决于在全局变量上，在设置 GIT_STRATEGY 时使用 anchor variables在不覆盖全局变量的情况下更改流水线任务。

stop_review_app 流水线任务需要定义以下关键字：

when，定义于：
- 流水线任务级别。
- 在规则条款中。如果你使用 rules: 和 when: manual，你还应该设置 allow_failure: true 以便可以完成流水线即使流水线任务没有运行。
environment:name
environment:action

此外，每个流水线任务都应该有匹配的 rules 或 only/except 配置。

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

stop_review_app 流水线任务可能不会包含在所有引用了review_app 流水线任务的流水线中。
无法触发 action: stop 来自动停止环境。

`environment:auto_stop_in`

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

例如，

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

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

`environment:kubernetes`

使用 kubernetes 关键字将部署配置为与你的项目相关联的 Kubernetes cluster 。

例如：

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

此配置使用 production Kubernetes 命名空间，将 deploy 流水线任务部署到 production环境。

Kubernetes 配置不支持由 GitLab 管理的 Kubernetes cluster。

`environment:deployment_tier`

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

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

动态环境

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

例如：

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

在这个例子中，deploy as review app 流水线任务被标记为动态部署创建 review/$CI_COMMIT_REF_NAME 环境。$CI_COMMIT_REF_NAME 是由 Runner 设置的 CI/CD 变量。$CI_ENVIRONMENT_SLUG 变量基于环境名称，可适用于 URL 中。如果 deploy as review app 流水线任务在名为 pow 的分支中运行，则这个环境可以通过 https://review-pow.example.com/ 这样的 URL 访问。

常见的用法是为分支创建动态环境并使用它们作为审查应用程序。你可以在以下位置查看使用 Review Apps 的示例 https://gitlab.com/gitlab-examples/review-apps-nginx/。

`cache`

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

如果在流水线任务范围之外定义了 cache，则它会是一个全局设置并且所有流水线任务都将使用该配置。

缓存在流水线和流水线任务之间共享。缓存在 artifacts 之前恢复。

`cache:paths`

使用 paths 命令选择要缓存的文件或目录。路径相对于项目目录 ($CI_PROJECT_DIR)，不能直接链接到项目目录之外。你可以使用使用 glob 的通配符模式。

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

rspec:
  script: test
  cache:
    paths:
      - binaries/*.apk
      - .config

本地定义的缓存覆盖全局定义的选项。以下例子中 rspec 流水线任务只缓存 binaries/：

cache:
  paths:
    - my/files

rspec:
  script: test
  cache:
    key: rspec
    paths:
      - binaries/

缓存在流水线任务之间是共享的，因此如果你使用不同的不同流水线任务的路径，你还应该设置不同的 cache:key，否则缓存内容可能会被覆盖。

`cache:key`

key 关键字定义了流水线任务之间缓存的亲和性。你可以为所有流水线任务使用一个缓存，或者为流水线任务生成缓存，或为每个分支生成缓存，或任何其他适合你工作流程的方式来生成缓存。你可以微调缓存，包括在不同流水线任务甚至不同分支之间缓存数据。

cache:key 变量可以使用任何预定义变量。如果不是设置，默认值只是字面上的 default，这意味着默认情况下一切缓存都在流水线和流水线任务之间共享。

比如，要为每个分支启用缓存：

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - binaries/

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

cache:
  key: "%CI_COMMIT_REF_SLUG%"
  paths:
    - binaries/

cache:key 变量不能包含 / 字符或等效字符 URI 编码的 %2F，也禁止仅由点（.、%2E）组成的值。

如果未找到指定的 cache:key，你可以指定使用 fallback 缓存键。

多个缓存

你最多可以有四个缓存：

test-job:
  stage: build
  cache:
    - key:
        files:
          - Gemfile.lock
      paths:
        - vendor/ruby
    - key:
        files:
          - yarn.lock
      paths:
        - .yarn-cache/
  script:
    - bundle install --path=vendor
    - yarn install --cache-folder .yarn-cache
    - echo Run tests...

如果多个缓存与一个 Fallback 缓存键组合在一起，如果未找到多个缓存，则多次获取回退。

回退缓存键

你可以使用$CI_COMMIT_REF_SLUG variable 来指定你的cache:key。例如，如果你的 $CI_COMMIT_REF_SLUG 是 test 你可以设置一个流水线任务下载标有 test 的缓存。

如果没有找到带有这个标签的缓存，也就是缓存不存在时，你可以指定使用CACHE_FALLBACK_KEY。

在下面的例子中，如果未找到 $CI_COMMIT_REF_SLUG，则流水线任务使用通过CACHE_FALLBACK_KEY变量定义的键：

variables:
  CACHE_FALLBACK_KEY: fallback-key

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - binaries/

`cache:key:files`

cache:key:files 关键字扩展了 cache:key 功能，使其可以更容易重用一些缓存，并减少重建它们的频率，从而加快后续流水线运行。

当你引用了 cache:key:files 时，你还必须列出用于生成密钥的项目文件（最多两个文件）。缓存 key 是根据指定文件的最近提交（最多两个，如果列出了两个文件）计算的 SHA 校验的。如果指定文件在任何提交中都没有更改，那么后退键是 default。

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 都使用新的缓存，而不是重建这些依赖项。

`cache:key:prefix`

当你想将前缀与通过 cache:key:files 计算的 SHA 结合起来时，将 prefix 关键字与 key:files 一起使用。例如，如果添加了 test 作为 prefix，结果 key 为test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5。如果给定文件在任何提交中都没有更改，则会在 default 上添加前缀，因此示例中的 key 是 test-default。

像cache:key一样，prefix可以使用任何预定义变量，但不能包括：

/ 字符（或等效的 URI 编码的 %2F）
仅由 . 组成的值（或等效的 URI 编码的 %2E）

cache:
  key:
    files:
      - Gemfile.lock
    prefix: ${CI_JOB_NAME}
  paths:
    - vendor/ruby

rspec:
  script:
    - bundle exec rspec

例如，添加了 $CI_JOB_NAME 的 prefix 后密钥看起来像：rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5，并且流水线任务缓存在不同的分支之间共享。如果某个分支中的 Gemfile.lock 发生变化，则该分支对 cache:key:files 有一个新的 SHA 校验并生成一个新的缓存 key，并为该键创建一个新的缓存。如果没有找到 Gemfile.lock，则将前缀添加到 default，因此示例中的 key 会是 rspec-default。

`cache:untracked`

设置 untracked: true 以缓存 Git 中未跟踪的所有文件存储库：

rspec:
  script: test
  cache:
    untracked: true

缓存所有 Git 未跟踪文件和 binaries 中的文件：

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

`cache:when`

cache:when 根据流水线任务的状态来定义何时保存缓存。你可以将 cache:when 设置为：

on_success（默认）：仅在流水线任务成功时保存缓存。
on_failure：仅在流水线任务失败时保存缓存。
always：始终保存缓存。

例如，无论流水线任务是否成功，都要存储缓存：

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

`cache:policy`

缓存流水线任务的默认行为是在开始执行时下载文件，并在最后重新上传它们。任何流水线任务的更改将保留以供将来运行。这种行为被称为pull-push缓存政策。

如果你知道该流水线任务不会更改缓存文件，则可以跳过上传步骤，通过在流水线任务中设置 policy: pull。可以在较早的阶段中添加普通缓存流水线任务以确保缓存保持更新：

stages:
  - setup
  - test

prepare:
  stage: setup
  cache:
    key: gems
    paths:
      - vendor/bundle
  script:
    - bundle install --deployment

rspec:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - bundle exec rspec ...

当你有许多使用缓存并行执行的流水线任务时，请使用 pull 策略。该策略可以加速流水线任务执行并减少缓存服务器上的负载。

如果你的流水线任务无条件地重新创建缓存，参考之前的内容，可以跳过下载步骤。为此，可以将 policy: push 添加到流水线任务中。

`artifacts`

使用 artifacts 指定文件和目录列表。当它 succeeds, fails, or always 时附加到流水线任务中。

流水线任务完成后， artifacts将发送到 codechina。如果他们的大小不超过 500M (目前设置的最大 artifacts 大小)，就可以在 UI 中进行下载。

默认情况下，后期的流水线任务会自动下载所有通过早期阶段的流水线任务创建的 artifacts。你可以使用 dependencies 命令控制流水线任务中的 artifacts下载行为。

使用 needs 关键字时，流水线任务只能下载来自在 needs 配置中定义的流水线任务的 artifacts。

默认情况下，仅为成功的流水线任务收集流水线任务 artifacts，并且在 caches 之后恢复 artifacts。

`dependencies`

默认情况下，前一阶段的所有 artifacts 将传递给每个流水线任务。但是，你可以使用 dependencies 关键字来定义要从中获取 artifacts 的有限流水线任务列表。你还可以设置一个完全不下载任何 artifacts流水线任务。

要使用此功能，请在流水线任务上下文中定义 dependencies 并提供一个应从先前流水线任务中下载 artifacts的流水线任务列表。

你可以在当前阶段之前执行的阶段定义流水线任务。如果你从当前或即将到来的阶段定义流水线任务，则会发生错误。

要防止流水线任务下载 artifacts，请定义一个空数组。

当你使用 dependencies 时，并不考虑上一个流水线任务的状态。如果流水线任务失败或者是未触发的手动流水线任务，则不会发生错误。

以下示例定义了两个带有 artifacts的流水线任务：build:osx 和 build：linux。当 test:osx 执行时，build:osx 中的 artifacts 在构建的上下文中下载和提取。同样的事情发生于 test:linux 和来自 build:linux 的 artifacts。

流水线任务 deploy 下载所有先前流水线任务的 artifacts，因为 stage 优先级：

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

当依赖流水线任务失败时

如果设置为依赖项的流水线任务 artifacts是 过期的 或 已删除，则依赖流水线任务失败。

`artifacts:exclude`

exclude 可以防止将文件添加到 artifacts中。

类似于 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`

使用 expire_in 指定流水线任务的 artifacts 在它们过期并被删除之前存储多长时间。expire_in 设置不会影响到：

来自最新流水线任务的 artifacts，除非保留最新的流水线任务 artifacts是在项目级别禁用的。
流水线 artifacts。以下情况的到期日期将无法指定：
- 来自最新流水线的流水线 artifacts将永远保留。
- 其它一周后删除 artifacts 的流水线。

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

要在上传后一周使 artifacts过期，你可以这样设置：

job:
  artifacts:
    expire_in: 1 week

当 artifacts上传并存储之后，到期时间段开始启动计时。如果到期时间未定义，则默认为 30 天。

要覆盖到期日期并保护 artifacts不被自动删除，你可以这样做：

使用流水线任务页面上的保留按钮。
将 expire_in 的值设置为 never。

过期后， artifacts 默认每小时删除一次（使用 cron 流水线任务），并且不再可以进行访问。

`artifacts:expose_as`

使用 expose_as 关键字在合并请求 UI 中公开流水线任务的 artifacts。

例如，要匹配单个文件：

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

在进行了如上的配置后，会在相关的合并请求中添加一个 artifact 1 的链接并指向 file1.txt。要访问链接，在合并请求概述中的流水线图下方选择 **查看暴露的 artifacts**即可。

匹配整个目录的示例：

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

注意事项：

使用变量定义 artifacts:paths 时，不会在合并请求 UI 中显示 artifacts。
每个合并请求最多可以显示 10 个流水线任务的 artifacts。
不支持全局模式。
如果指定了目录，并且目录中不止一个文件的话，则链接到流水线任务 artifacts 浏览器。
对于带有.html、.htm、.txt、.json、.xml 和 .log 扩展名，且Pages ：
- 启用，则自动呈现 artifacts。
- 未启用，文件显示在 artifacts 浏览器中。

`artifacts:name`

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

要使用当前流水线任务的名称创建存档，你可以这样做：

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

使用当前分支或标记的名称创建存档，仅包含 binaries 目录中的文件，你可以这样做：

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

如果你的分支名称包含 /（例如feature/my-feature）建议使用 $CI_COMMIT_REF_SLUG 而不是$CI_COMMIT_REF_NAME 来命名 artifacts。

使用当前流水线任务和当前分支的名称或 tag 创建存档，并且仅包含 binaries 目录中的文件，你可以这样做：

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 的通配符模式和 doublestar.Glob 模式。

要限制特定流水线任务从哪些流水线任务获取 artifacts，请参阅 dependencies。

要包含 binaries 和 .config 中的所有文件，你可以这样做：

artifacts:
  paths:
    - binaries/
    - .config

要禁用 artifacts 传递，请使用空 dependencies 来定义流水线任务：

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

你可能只想为发行版创建 artifacts 以避免使用太多的临时 artifacts 去占用构建服务器的存储。

仅为发行版创建 artifacts（default-job 不创建 artifacts），你可以这样做：

default-job:
  script:
    - mvn test -U
  except:
    - tags

release-job:
  script:
    - mvn package -U
  artifacts:
    paths:
      - target/*.war
  only:
    - tags

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

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

`artifacts:public`

使用 artifacts:public 来确定流水线任务的 artifacts 是否公开可用。

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

artifacts:
  public: true

拒绝匿名用户和访客用户对公共流水线中 artifacts的读取访问，可以将 artifacts:public 设置为 false：

artifacts:
  public: false

`artifacts:reports`

使用 artifacts:reports从流水线任务中收集测试报告、代码质量报告和安全报告。它还会在合并请求和流水线视图的 UI 中公开这些报告。

无论流水线任务结果如何（成功或失败），都会收集测试报告。你可以使用 artifacts:expire_in 来设置过期时间。

如果你还希望能够浏览报告输出文件，请使用artifacts:paths 关键字。

`artifacts:reports:cobertura`

cobertura 报告收集 Cobertura 覆盖 XML 文件。收集的 Cobertura 覆盖率报告作为 artifacts 上传并显示在合并请求中。

Cobertura 最初是为 Java 开发的，但也有很多其他语言（如 JavaScript、Python、Ruby 等）的第三方端口。

`artifacts:reports:codequality`

codequality 报告收集代码质量问题。

收集的代码质量报告作为 artifacts 上传到并在合并请求中汇总。

`artifacts:reports:dotenv`

dotenv 报告收集一组环境变量作为 artifacts。

收集的变量被注册为流水线任务的运行时创建的变量，这对于在流水线任务完成后设置动态环境 URL 会非常有用。

原始 dotenv 规则有几个例外：

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

`artifacts:reports:junit`

junit 报告收集 JUnit 报告格式 XML 文件作为 artifacts。虽然 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

收集到的单元测试报告作为 artifacts 上传并显示在合并请求中。

如果你使用的 JUnit 工具导出到多个 XML 文件，请指定单个流水线任务中的多个测试报告路径将它们连接成一个文件。使用文件名模式（junit: rspec-*.xml），文件名数组（junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]），或其组合（junit: [rspec.xml, test-results/TEST-*.xml]）的方式。

`artifacts:reports:terraform`

terraform 报告获取 Terraform tfplan.json 文件。收集到的计划报告作为 artifacts上传并显示在合并请求中。

`artifacts:untracked`

使用 artifacts:untracked 将所有 Git 未跟踪文件添加为 artifacts（以及使用 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 在流水线任务失败或不论失败与否时上传 artifacts 。

artifacts:when 可以设置为以下值之一：

on_success（默认）：仅在流水线任务成功时上传 artifacts。
on_failure：仅在流水线任务失败时上传 artifacts。
always：始终上传 artifacts。例如，当需要上传 artifacts 对失败的测试进行故障排除时会非常有用。

例如，仅在流水线任务失败时上传 artifacts：

job:
  artifacts:
    when: on_failure

`coverage`

使用 coverage 配置如何从流水线任务输出。

正则表达式是此处预期的唯一有效值。所以，使用 / 包裹是强制性的，以一致且明确地表示一个正则表达式字符串。如果需要的话，你必须转义特殊字符以从字面上匹配它们。

例如：

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

如果流水线任务输出中至少有一行与正则表达式匹配，则覆盖率会显示在 UI 中。如果流水线任务输出中有多个匹配的行，则使用最后一行。对于匹配的行，第一次出现 \d+(\.\d+)? 是代码覆盖率。前导零被删除。

子流水线的覆盖率输出未记录或显示。检查相关问题更多细节。

###重试

介绍在 GitLab 11.5 中，你可以控制重试哪些故障。

使用 retry 配置一个流水线任务的重试次数失败的情况。

当一个流水线任务失败时，该流水线任务被重新处理，直到达到由 retry 关键字指定的限制。

如果 retry 设置为 2，并且流水线任务在第二次运行（第一次重试）中成功，则不会重试。 retry 值必须是一个正整数，从 0 到 2 （最多重试两次，总共运行三次）。

以下示例重试所有失败情况：

测试：
  脚本：rspec
  重试：2
``

默认情况下，在所有失败情况下都会重试流水线任务。为了更好地控制
对于重试失败，“重试”可以是具有以下键的散列：

- `max`：最大重试次数。
- `when`：要重试的失败案例。

仅重试运行器系统故障最多两次：

```yaml
测试：
  脚本：rspec
  重试：
    最大：2
    时间：runner_system_failure
``

如果除了流道系统故障之外还有其他故障，流水线任务
不重试。

要重试多个失败案例，`when` 也可以是一个失败数组：

```yaml
测试：
  脚本：rspec
  重试：
    最大：2
    什么时候：
      - runner_system_failure
      - 卡住_or_timeout_failure
``

`when` 的可能值为：

<!--
  如果你更改以下任何值，请确保更新 `RETRY_WHEN_IN_DOCUMENTATION`
  `spec/lib/gitlab/ci/config/entry/retry_spec.rb` 中的数组。
  那里的测试确保所有记录在案
  值作为配置选项有效，因此应始终
  与本文档保持同步。
-->

- `always`：在任何失败时重试（默认）。
- `unknown_failure`：失败原因未知时重试。
- `script_failure`：脚本失败时重试。
- `api_failure`：API 失败时重试。
- `stuck_or_timeout_failure`：当流水线任务卡住或超时时重试。
- `runner_system_failure`：如果存在运行器系统故障（例如，流水线任务设置失败），则重试。
- `missing_dependency_failure`：如果缺少依赖项，请重试。
- `runner_unsupported`：如果跑步者不受支持，则重试。
- `stale_schedule`：如果无法执行延迟的流水线任务，请重试。
- `job_execution_timeout`：如果脚本超过为流水线任务设置的最大执行时间，则重试。
- `archived_failure`：如果流水线任务已存档且无法运行，请重试。
- `unmet_prerequisites`：如果流水线任务未能完成先决任务，则重试。
- `scheduler_failure`：如果调度程序未能将流水线任务分配给运行程序，则重试。
- `data_integrity_failure`：如果检测到结构完整性问题，请重试。

你可以使用变量指定[特定流水线任务执行阶段的重试次数](../runners/README.md#job-stages-attempts)。

###`超时`

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) 在 GitLab 12.3 中。

使用 `timeout` 为特定流水线任务配置超时。例如：

```yaml
建造：
  脚本：build.sh
  超时：3小时30分钟

测试：
  脚本：rspec
  超时时间：3h 30m
``

流水线任务级超时可以超过
[项目级超时](../pipelines/settings.md#timeout) 但不能
超过跑步者特定的超时时间。

###`平行`

> [介绍](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) 在 GitLab 11.5 中。

使用 `parallel` 配置要并行运行的流水线任务实例的数量。
该值可以是 2 到 50。

`parallel` 关键字创建并行运行的同一流水线任务的 N 个实例。
它们的命名顺序是从 `job_name 1/N` 到 `job_name N/N`：

```yaml
测试：
  脚本：rspec
  平行：5
``

每个并行流水线任务都有一个“CI_NODE_INDEX”和“CI_NODE_TOTAL”
[预定义 CI/CD 变量](../variables/README.md#predefined-cicd-variables) 设置。

不同的语言和测试套件有不同的方法来实现并行化。
例如，使用 [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters)
和 RSpec 并行运行 Ruby 测试：

```红宝石
# 宝石文件
来源“https://rubygems.org”

宝石'rspec'
gem 'semaphore_test_boosters'
``

```yaml
测试：
  并行：3
  脚本：
    - 捆
    - 捆绑执行 rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL
``

警告：
Test Boosters 向作者报告使用统计数据。

然后，你可以导航到新流水线构建的 **Jobs** 选项卡并查看你的 RSpec
流水线任务分为三个独立的流水线任务。

#### 并行`矩阵`流水线任务

> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/15356) 在 GitLab 13.3 中。

使用 `matrix:` 在单个流水线中并行运行流水线任务多次，
但每个流水线任务实例都有不同的变量值。
可以有 2 到 50 个流水线任务岗位。

流水线任务只有在有多个跑步者或单个跑步者时才能并行运行
[配置为同时运行多个流水线任务](#use-your-own-runners)。

每个流水线任务都获得相同的 `CI_NODE_TOTAL` [CI/CD 变量](../variables/README.md#predefined-cicd-variables) 值和唯一的 `CI_NODE_INDEX` 值。

```yaml
部署堆栈：
  阶段：部署
  脚本：
    - 垃圾箱/部署
  平行：
    矩阵：
      - 供应商：aws
        堆：
          - 监控
          - 应用程序1
          - 应用程序2
      - 提供者：ovh
        堆栈：[监控、备份、应用程序]
      - 提供者：[gcp，vultr]
        堆栈：[数据，处理]
``

以下示例生成 10 个并行的 `deploystacks` 流水线任务，每个流水线任务具有不同的值
对于 `PROVIDER` 和 `STACK`：

```明文
deploystacks：[aws，监控]
部署堆栈：[aws，app1]
部署堆栈：[aws，app2]
deploystacks: [ovh, 监控]
部署堆栈：[ovh，备份]
部署堆栈：[ovh，应用程序]
部署堆栈：[gcp，数据]
部署堆栈：[gcp，处理]
部署堆栈：[vultr，数据]
部署堆栈：[vultr，处理]
``

流水线任务命名风格[在 GitLab 13.4 中改进](https://gitlab.com/gitlab-org/gitlab/-/issues/230452)。

#####一维`矩阵`流水线任务

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/26362) 在 GitLab 13.5 中。

你还可以在单个流水线任务中使用一维矩阵：

```yaml
部署堆栈：
  阶段：部署
  脚本：
    - 垃圾箱/部署
  平行：
    矩阵：
      - 提供商：[aws、ovh、gcp、vultr]
``

##### 并行`matrix` 触发流水线任务

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/270957) 在 GitLab 13.10 中。

使用 `matrix:` 在单个流水线中多次并行运行 [trigger](#trigger) 流水线任务，
但每个流水线任务实例都有不同的变量值。

```yaml
部署堆栈：
  阶段：部署
  扳机：
    包括：path/to/child-pipeline.yml
  平行：
    矩阵：
      - 供应商：aws
        堆栈：[监控，app1]
      - 提供者：ovh
        堆栈：[监控、备份]
      - 提供者：[gcp，vultr]
        堆栈：[数据]
``

此示例生成 6 个并行的 `deploystacks` 触发器流水线任务，每个流水线任务具有不同的值
对于 `PROVIDER` 和 `STACK`，它们使用这些变量创建了 6 个不同的子流水线。

```明文
deploystacks：[aws，监控]
部署堆栈：[aws，app1]
deploystacks: [ovh, 监控]
部署堆栈：[ovh，备份]
部署堆栈：[gcp，数据]
部署堆栈：[vultr，数据]
``

###`触发器`

> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) 在 [GitLab Premium](https://about.gitlab.com/pricing/) 11.8。
> - [移动](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) 在 12.8 中免费使用 GitLab。

使用 `trigger` 定义下游流水线触发器。当 GitLab 开始一个 `trigger` 流水线任务时，
创建下游流水线。

带有`trigger` 的流水线任务只能使用[有限的关键字集](../multi_project_pipelines.md#limitations)。
例如，你不能用 [`script`](#script), [`before_script`](#before_script),
或 [`after_script`](#after_script)。

你可以使用此关键字创建两种不同类型的下游流水线：

- [多项目流水线](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml)
- [子流水线](../parent_child_pipelines.md)

[在 GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) 及更高版本，你可以
查看哪个流水线任务触发了下游流水线。在[流水线图](../pipelines/index.md#visualize-pipelines)中，
将鼠标悬停在下游流水线流水线任务上。

在 [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) 及更高版本中，你
可以在与 `trigger` 相同的流水线任务中使用 [`when:manual`](#whenmanual)。在 GitLab 13.4 和
早些时候，将它们一起使用会导致错误 `jobs:#{job-name} when should be on_success, on_failure or always`。
你[无法使用 API 启动`手动`触发器流水线任务](https://gitlab.com/gitlab-org/gitlab/-/issues/284086)。

#### 多项目流水线的基本`trigger` 语法

你可以使用 `trigger` 关键字配置下游触发器
下游项目的完整路径：

```yaml
规格：
  阶段：测试
  脚本：bundle exec rspec

分期：
  阶段：部署
  触发器：我的/部署
``

#### 多项目流水线的复杂`trigger` 语法

你可以配置一个 GitLab 用来创建的分支名称
具有以下功能的下游流水线：

```yaml
规格：
  阶段：测试
  脚本：bundle exec rspec

分期：
  阶段：部署
  扳机：
    项目：我的/部署
    分支：稳定
``

要从触发的流水线镜像状态：

```yaml
trigger_job:
  扳机：
    项目：我的/项目
    策略：依赖
``

要从上游流水线镜像状态：

```yaml
上游桥：
  阶段：测试
  需要：
    流水线：其他/项目
``

#### 子流水线的`trigger` 语法

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) 在 GitLab 12.7 中。

要创建 [子流水线](../parent_child_pipelines.md)，请指定路径
包含子流水线配置的 YAML 文件：

```yaml
trigger_job:
  扳机：
    包括：path/to/child-pipeline.yml
``

类似于[多项目流水线](../multi_project_pipelines.md#mirroring-status-from-triggered-pipeline)，
可以从触发的流水线中镜像状态：

```yaml
trigger_job:
  扳机：
    包括：
      - 本地：path/to/child-pipeline.yml
    策略：依赖
``

##### 使用生成的配置文件触发子流水线

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) 在 GitLab 12.9 中。

你还可以从 [动态生成的配置文件](../parent_child_pipelines.md#dynamic-child-pipelines) 触发子流水线：

```yaml
生成配置：
  阶段：构建
  脚本：生成-ci-config > 生成-config.yml
  文物：
    路径：
      - 生成的 config.yml

子流水线：
  阶段：测试
  扳机：
    包括：
      -  `artifacts`：生成的 config.yml
        工作：生成配置
``

`generated-config.yml` 从 `artifacts`中提取并用作配置
用于触发子流水线。

##### 使用来自另一个项目的文件触发子流水线

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/205157) 在 GitLab 13.5 中。

使用来自同一私有项目的文件触发子流水线
GitLab 实例，使用 [`include:file`](#includefile)：

```yaml
子流水线：
  扳机：
    包括：
      - 项目：'我的组/我的流水线库'
        参考：'主要'
        文件：'/path/to/child-pipeline.yml'
``

#### 使用 `trigger:strategy` 链接流水线

默认情况下，`trigger` 流水线任务以 `success` 状态完成
一旦创建了下游流水线。

要强制 `trigger` 流水线任务等待下游（多项目或子）流水线完成，请使用
`策略：依赖`。此设置使触发流水线任务以“正在运行”状态等待，直到触发
流水线完成。此时，`trigger` 流水线任务完成并显示与
下游流水线任务。

此设置有助于保持流水线执行的线性。在以下示例中，流水线任务来自
后续阶段等待触发的流水线成功完成之前
开始，这减少了并行化。

```yaml
trigger_job:
  扳机：
    包括：path/to/child-pipeline.yml
    策略：依赖
``

#### 通过 API 调用触发流水线

要强制重建特定分支、标记或提交，你可以使用 API 调用
带有触发令牌。

触发标记不同于 [`trigger`](#trigger) 关键字。

[在触发器文档中阅读更多内容。](../triggers/README.md)

###`可中断`

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) 在 GitLab 12.3 中。

使用 `interruptible` 表示如果新的流水线运行变得多余，则应取消正在运行的流水线任务。
默认为`false`（不可中断）。尚未开始（待处理）的流水线任务被认为是可中断的
并且可以安全取消。
此值仅在 [自动取消冗余流水线功能](../pipelines/settings.md#auto-cancel-redundant-pipelines) 时使用
已启用。

启用后，如果以下任一情况为真，则在同一分支上启动新流水线时会立即取消流水线：

- 流水线中的所有流水线任务都设置为可中断的。
- 任何不间断的工作尚未开始。

将流水线任务设置为可以在启动后安全取消的可中断流水线任务（例如，构建流水线任务）。

在以下示例中，新流水线运行会导致现有运行流水线变为：

- 取消，如果只有 `step-1` 正在运行或未决。
- 不会取消，一旦 `step-2` 开始运行。

不间断流水线任务开始运行后，流水线无法取消。

```yaml
阶段：
  - 阶段1
  - 阶段2
  - 第三阶段

步骤1：
  阶段：stage1
  脚本：
    - echo "可以取消。"
  可中断：真

第2步：
  阶段：阶段2
  脚本：
    - echo "不能取消。"

第 3 步：
  阶段：stage3
  脚本：
    - echo "因为第 2 步不能取消，所以这一步永远不能取消，即使它被设置为可中断。"
  可中断：真
``

###`resource_group`

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) 在 GitLab 12.7 中。

有时在一个环境中同时运行多个流水线任务或流水线
可能会导致部署过程中出现错误。

为避免这些错误，请使用 `resource_group` 属性来确保
跑步者不会同时运行某些流水线任务。资源组的行为相似
到其他编程语言中的信号量。

当在 `.codechina-ci.yml` 文件中为流水线任务定义了 `resource_group` 关键字时，
同一项目的不同流水线中的流水线任务执行是相互排斥的。
如果属于同一资源组的多个流水线任务同时入队，
跑步者只选择其中一项工作。其他工作等到
`resource_group` 是免费的。

例如：

```yaml
部署到生产：
  脚本：部署
  资源组：生产
``

在这种情况下，两个独立流水线中的两个“部署到生产”流水线任务永远不能同时运行。因此，
你可以确保并发部署永远不会发生在生产环境中。

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

`resource_group` 值只能包含字母、数字、`-`、`_`、`/`、`$`、`{`、`}`、`.` 和空格。
它不能以`/`开头或结尾。

有关更多信息，请参阅 [部署安全](../environments/deployment_safety.md)。

#### 具有跨项目/父子流水线的流水线级并发控制

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/39057) 在 GitLab 13.9 中。

你可以为对并发敏感的下游流水线定义`resource_group`
处决。[`trigger` 关键字](#trigger) 可以触发下游流水线。这
[`resource_group` 关键字](#resource_group) 可以与它共存。这有助于控制
部署流水线的并发性，同时运行非敏感流水线任务。

以下示例在一个项目中有两个流水线配置。当流水线开始运行时，
非敏感流水线任务首先执行，不受其他并发执行的影响
流水线。但是，GitLab 确保之前没有其他部署流水线在运行
触发部署（子）流水线。如果其他部署流水线正在运行，GitLab 等待
直到这些流水线完成，然后再运行另一个。

```yaml
# .codechina-ci.yml（父流水线）

建造：
  阶段：构建
  脚本：回声“建筑...”

测试：
  阶段：测试
  脚本：回声“测试...”

部署：
  阶段：部署
  扳机：
    包括：deploy.codechina-ci.yml
    策略：依赖
  资源组：AWS 生产
``

```yaml
# deploy.codechina-ci.yml（子流水线）

阶段：
  - 条款
  - 部署

条款：
  阶段：准备
  脚本：回声“供应...”

部署：
  阶段：部署
  脚本：echo“正在部署...”
``

你必须定义 [`strategy:depend`](#linking-pipelines-with-triggerstrategy)
使用`trigger` 关键字。这确保在下游流水线之前不会释放锁
完成。

###`发布`

> [介绍](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) 在 GitLab 13.2 中。

使用 `release` 创建一个 [release](../../user/project/releases/index.md)。
需要 [`release-cli`](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs)
在你的 GitLab Runner Docker 或 shell 执行器中可用。

支持这些关键字：

- [`tag_name`](#releasetag_name)
- [`描述`](#releasedescription)
- [`name`](#releasename)（可选）
- [`ref`](#releaseref)（可选）
- [`里程碑`](#releasemilestones)（可选）
- [`released_at`](#releasereleased_at)（可选）
- [`assets:links`](#releaseassetslinks)（可选）

仅当流水线任务处理没有错误时才会创建发布。如果 Rails API
在发布创建期间返回错误，`release` 流水线任务失败。

#### `release-cli` Docker 镜像

你必须指定用于 `release-cli` 的 Docker 镜像：

```yaml
图片：registry.gitlab.com/gitlab-org/release-cli:latest
``

#### shell 执行程序的`release-cli`

> [介绍](https://gitlab.com/gitlab-org/release-cli/-/issues/21) 在 GitLab 13.8 中。

对于 GitLab Runner shell 执行程序，你可以为你的 [支持的操作系统和架构] (https://release-cli-downloads.s3.amazonaws.com/latest/index.html) 手动下载并安装 `release-cli`。
安装后，你应该可以使用`release` 关键字。

**在 Unix/Linux 上安装**

1. 下载适用于你系统的二进制文件，以下示例适用于 amd64 系统：

  ```壳
  curl --location --output /usr/local/bin/release-cli "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-linux-amd64"
  ``

1. 赋予其执行权限：

  ```壳
  须藤 chmod +x /usr/local/bin/release-cli
  ``

1. 验证`release-cli` 是否可用：

  ```壳
  $ release-cli -v

  发布 cli 版本 0.6.0
  ``

**在 Windows PowerShell 上安装**

1. 在你系统的某处创建一个文件夹，例如`C:\GitLab\Release-CLI\bin`

  ```壳
  New-Item -Path 'C:\GitLab\Release-CLI\bin' -ItemType 目录
  ``

1.下载可执行文件：

  ```壳
  PS C:\> Invoke-WebRequest -Uri "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI \bin\release-cli.exe”

      目录：C:\GitLab\Release-CLI
  模式 LastWriteTime 长度 名称
  ---- ------------- ------ ----
  d----- 3/16/2021 4:17 AM

  ``

1. 将目录添加到你的 `$env:PATH`：

  ```壳
  $env:PATH += ";C:\GitLab\Release-CLI\bin"
  ``

1. 验证`release-cli` 是否可用：

  ```壳
  PS C:\> release-cli -v

  发布 cli 版本 0.6.0
  ``

#### 使用自定义 SSL CA 证书颁发机构

你可以使用 `ADDITIONAL_CA_CERT_BUNDLE` CI/CD 变量来配置自定义 SSL CA 证书颁发机构，
当`release-cli`使用带有自定义证书的HTTPS通过API创建发布时，它用于验证对等点。
`ADDITIONAL_CA_CERT_BUNDLE` 值应包含
[X.509 PEM 公钥证书的文本表示](https://tools.ietf.org/html/rfc7468#section-5.1)
或包含证书颁发机构的`path/to/file`。
例如，要在 `.codechina-ci.yml` 文件中配置此值，请使用以下命令：

```yaml
释放：
  变量：
    ADDITIONAL_CA_CERT_BUNDLE: |
        -----开始认证-----
        MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
        ...
        jWgmPqF3vUbZE0EySetPJquRFRKIesyJuBFMAs=
        -----结束证书-----
  脚本：
    - 回声“创建发布”
  释放：
    名称：'我很棒的版本'
    tag_name: '$CI_COMMIT_TAG'
``

`ADDITIONAL_CA_CERT_BUNDLE` 值也可以配置为
[UI 中的自定义变量](../variables/README.md#custom-cicd-variables),
要么作为一个`file`，它需要证书的路径，或者作为一个变量，
这需要证书的文本表示。

####`脚本`

除 [trigger](#trigger) 流水线任务之外的所有流水线任务都必须具有 `script` 关键字。一个`发布`
流水线任务可以使用脚本命令的输出，但如果出现以下情况，你可以使用占位符脚本
不需要脚本：

```yaml
脚本：
  - echo '发布工作'
``

[问题](https://gitlab.com/gitlab-org/gitlab/-/issues/223856) 存在以在即将发布的 GitLab 版本中删除此要求。

一个流水线可以有多个“发布”流水线任务，例如：

```yaml
ios-发布：
  脚本：
    - echo 'iOS 发布工作'
  释放：
    标签名称：v1.0.0-ios
    描述：'iOS 发布 v1.0.0'

安卓发布：
  脚本：
    - echo 'Android 发布工作'
  释放：
    标签名称：v1.0.0-android
    描述：'Android 发布 v1.0.0'
``

####`release:tag_name`

你必须为发布指定一个 `tag_name`。该标签可以引用现有的 Git 标签或
你可以指定一个新标签。

当存储库中不存在指定的标签时，将从流水线的关联 SHA 创建一个新标签。

例如，从 Git 标签创建发布时：

```yaml
工作：
  释放：
    标签名称：$CI_COMMIT_TAG
    description: '发布说明'
``

也可以创建任何唯一的标签，在这种情况下，`only: tags` 不是强制性的。
语义版本控制示例：

```yaml
工作：
  释放：
    标签名称：${MAJOR}_${MINOR}_${REVISION}
    description: '发布说明'
``

- 只有当流水线任务的主脚本成功时才会创建发布。
- 如果发布已经存在，则不会更新并且带有`release` 关键字的流水线任务失败。
- `release` 部分在 `script` 标签之后和 `after_script` 之前执行。

####`发布：名称`

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

####`发布：描述`

指定发布的详细描述。你还可以指定一个包含
描述。

##### 从文件中读取描述

> [介绍](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/67) 在 GitLab 13.7 中。

你可以在 `$CI_PROJECT_DIR` 中指定一个包含描述的文件。该文件必须是相对的
到项目目录（`$CI_PROJECT_DIR`），如果文件是一个符号链接，它就不能驻留
在 `$CI_PROJECT_DIR` 之外。`./path/to/file` 和文件名不能包含空格。

```yaml
工作：
  释放：
    标签名称：${MAJOR}_${MINOR}_${REVISION}
    描述：'./path/to/CHANGELOG.md'
``

####`发布：参考`

如果 `release: tag_name` 还不存在，则从 `ref` 创建发布。
`ref` 可以是提交 SHA、另一个标签名称或分支名称。

####`发布：里程碑`

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

####`release:released_at`

发布准备就绪的日期和时间。如果不是，则默认为当前日期和时间
定义。应该用引号引起来并以 ISO 8601 格式表示。

```json
发布时间：'2021-03-15T08:00:00Z'
``

####`发布：资产：链接`

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/271454) 在 GitLab 13.12 中。

在发布中包含 [资产链接](../../user/project/releases/index.md#release-assets)。

笔记：
需要 `release-cli` 版本 v0.4.0 或更高版本。

```yaml
资产：
  链接：
    - 名称：'资产1'
      网址：'https://example.com/assets/1'
    - 名称：'资产2'
      网址：'https://example.com/assets/2'
      文件路径：'/pretty/url/1' # 可选
      link_type: 'other' # 可选
``

#### `release` 的完整示例

如果你结合之前的 `release` 例子，你会得到两个选项，这取决于你如何生成
标签。你不能同时使用这些选项，因此请选择一个：

- 在推送 Git 标签或添加 Git 标签时创建发布
  通过转到 **Repository > Tags** 在 UI 中：

  ```yaml
  发布工作：
    阶段：发布
    图片：registry.gitlab.com/gitlab-org/release-cli:latest
    规则：
      - if: $CI_COMMIT_TAG # 手动创建标签时运行此流水线任务
    脚本：
      - echo '正在运行 release_job'
    释放：
      name: '发布 $CI_COMMIT_TAG'
      描述：'使用 release-cli $EXTRA_DESCRIPTION 创建' # $EXTRA_DESCRIPTION 必须被定义
      tag_name: '$CI_COMMIT_TAG' # 流水线中的其他地方。
      参考：'$CI_COMMIT_TAG'
      里程碑：
        - 'm1'
        - 'm2'
        - 'm3'
      released_at: '2020-07-15T08:00:00Z' # 可选，如果未定义则自动生成，或者可以使用变量。
      assets: # 可选，多个资产链接
        链接：
          - 名称：'资产1'
            网址：'https://example.com/assets/1'
          - 名称：'资产2'
            网址：'https://example.com/assets/2'
            文件路径：'/pretty/url/1' # 可选
            link_type: 'other' # 可选
  ``

- 要在提交推送或合并到默认分支时自动创建发布，
  使用一个用变量定义的新 Git 标签：

  笔记：
  在 `before_script` 或 `script` 中设置的环境变量不可用于扩展
  在同一份工作中。阅读更多关于
  [可能使变量可用于扩展](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400)。

  ```yaml
  准备工作：
    stage: prepare # 这个阶段必须在发布阶段之前运行
    规则：
      - 如果：$CI_COMMIT_TAG
        when: never # 手动创建标签时不要运行此流水线任务
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 当提交被推送或合并到默认分支时运行这个流水线任务
    脚本：
      - echo "EXTRA_DESCRIPTION=some message" >> variables.env # 生成 EXTRA_DESCRIPTION 和 TAG 环境变量
      - echo "TAG=v$(cat VERSION)" >> variables.env # 并附加到 variables.env 文件
    文物：
      报告：
        dotenv: variables.env # 使用 artifacts:reports:dotenv 将变量暴露给其他流水线任务

  发布工作：
    阶段：发布
    图片：registry.gitlab.com/gitlab-org/release-cli:latest
    需要：
      - 工作：prepare_job
        文物：真实
    规则：
      - 如果：$CI_COMMIT_TAG
        when: never # 手动创建标签时不要运行此流水线任务
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 当提交被推送或合并到默认分支时运行这个流水线任务
    脚本：
      - echo '为 $TAG 运行 release_job'
    释放：
      name: '发布 $TAG'
      描述：“使用 release-cli $EXTRA_DESCRIPTION 创建”# $EXTRA_DESCRIPTION 和 $TAG
      tag_name: '$TAG' # 变量必须在别处定义
      ref: '$CI_COMMIT_SHA' # 在流水线中。例如，在
      里程碑：# prepare_job
        - 'm1'
        - 'm2'
        - 'm3'
      released_at: '2020-07-15T08:00:00Z' # 可选，如果未定义则自动生成，或者可以使用变量。
      资产：
        链接：
          - 名称：'资产1'
            网址：'https://example.com/assets/1'
          - 名称：'资产2'
            网址：'https://example.com/assets/2'
            文件路径：'/pretty/url/1' # 可选
            link_type: 'other' # 可选
  ``

#### 将资产发布为通用包

你可以使用 [通用包](../../user/packages/generic_packages/) 来托管你的发布资产。
一个完整的例子，请参见 [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package /)
项目。

#### `release-cli` 命令行

`release` 节点下的条目被转换为 `bash` 命令行并发送
到 Docker 容器，其中包含 [release-cli](https://gitlab.com/gitlab-org/release-cli)。
你也可以直接从 `script` 条目调用 `release-cli`。

例如，如果你使用前面描述的 YAML：

```壳
release-cli create --name "Release $CI_COMMIT_SHA" --description "使用 release-cli $EXTRA_DESCRIPTION 创建" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\" :\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}
``

###`秘密`

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) 在 GitLab 13.4 中。

使用 `secrets` 指定流水线任务需要的 [CI/CD Secrets](../secrets/index.md)。它应该是一个哈希，
键应该是可供流水线任务使用的变量的名称。
每个秘密的值都保存在一个临时文件中。这个文件的路径存储在这些
变量。

#### `secrets:vault` **(PREMIUM)**

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) 在 GitLab 13.4 中。

使用 `vault` 指定 [Hashicorp's Vault](https://www.vaultproject.io/) 提供的机密。

这种语法有多种形式。最短的形式假定使用
[KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) 秘密引擎，
安装在默认路径 `kv-v2` 上。秘密路径的最后一部分是
字段来获取值：

```yaml
工作：
  秘密：
    数据库密码：
      vault: production/db/password # 转换为秘密 `kv-v2/data/production/db`，字段 `password`
``

你可以通过添加以 `@` 开头的后缀来指定自定义机密引擎路径：

```yaml
工作：
  秘密：
    数据库密码：
      vault: production/db/password@ops # 转换为秘密 `ops/data/production/db`，字段 `password`
``

在语法的详细形式中，你可以明确指定所有详细信息：

```yaml
工作：
  秘密：
    DATABASE_PASSWORD: # 转换为秘密 `ops/data/production/db`，字段 `password`
      保险库：
        引擎：
          名称： kv-v2
          路径：ops
        路径：生产/数据库
        字段：密码
``

###`页面`

使用 `pages` 将静态内容上传到 GitLab。内容
然后作为网站发布。你必须：

- 将任何静态内容放在 `public/` 目录中。
- 定义 [`artifacts`](#artifacts) 和 `public/` 目录的路径。

以下示例将所有文件从项目的根目录移动到
`public/` 目录。`.public` 解决 `cp` 也不会复制
`public/` 在无限循环中传递给自身：

```yaml
页数：
  阶段：部署
  脚本：
    - mkdir .public
    - cp -r * .public
    - mv .public 公共
  文物：
    路径：
      - 上市
  只要：
    - 主要的
``

查看 [GitLab Pages 用户文档](../.project/pages/index.md)。

###`继承`

> [介绍](https://gitlab.com/gitlaitlab/-/issues/207484) 在 GitLab 12.9 中。

使用 `inherit:` 来控制全局定义继承
和变量。

要启用或禁用所有 `default:` 或 `vs:` 关键字的继承，请使用：

- `default: true` 或 `default: fa
- `变量：真`或`变量：假`

要仅继承 `default:` 关键字或 `var` 的子集，请指定
你想继承。任何未列出的都是**不*用
以下格式之一：

```yaml
继承：
  默认值：[关键字 1，关键字 2]
  变量：[VARIABLE1, VARIABLE2]
``

或者：

```yaml
继承：
  默认：
    - 关键字 1
    - 关键字 2
  变量：
    - 变量 1
    - 变量 2
``

在以下示例中：

-`rubocop`：
  - 继承：没有。
- `rspec`：
  - 继承：默认的`image` 和`WEBHOO变量。
  - **不** 继承：默认的`before_sc和`DOMAIN` 变量。
-`水豚`：
  - 继承：默认的`before_script` `。
  - **不** 继承：`DOMAIN` 和`WEBH` 变量。
-`业力`：
  - 继承：默认的`image` 和`before`，以及`DOMAIN` 变量。
  - **不** 继承：`WEBHOOK_URL` 

```yaml
默认：
  图像：'红宝石：2.4'
  之前_脚本：
    - 回声你好世界

变量：
  域：example.com
  WEBHOOK_URL: https://my-webhooke.com

防暴警察：
  继承：
    默认值：假
    变量：假
  脚本：捆绑执行 rubocop

规格：
  继承：
    默认值：[图像]
    变量：[WEBHOOK_URL]
  脚本：bundle exec rspec

水豚：
  继承：
    变量：假
  脚本：捆绑执行水豚

业力：
  继承：
    默认值：真
    变量：[域]
  剧本：业力
``

##`变量`

> 在 GitLab Runner v0.5.0 中引入。

[CI/CD 变量](../variables/README.传递给流水线任务的可配置值。
它们可以在全局和每个流水线任务中设置。

有两种类型的变量。

- [自定义变量](../variables/READMstom-cicd-variables):
  你可以在 GitLab UI 中的 `.gitlal` 文件中定义它们的值，
  或通过使用 API。你还可以在 GitL中输入变量
  [手动运行流水线](../pipelines/indun-a-pipeline-manually)。
- [预定义变量](../variables/predeariables.md):
  这些值由跑步者自己设置。
  一个例子是`CI_COMMIT_REF_NAME项目构建的分支或标签。

定义变量后，你可以在所有执行的中使用它。

变量用于非敏感项目配置，例如：

```yaml
变量：
  DEPLOY_SITE: "https://example.c

部署_流水线任务：
  阶段：部署
  脚本：
    - 部署脚本 --url $DEPLOY_SITE "/"

deploy_review_job:
  阶段：部署
  变量：
    REVIEW_PATH: "/review"
  脚本：
    - deploy-review-script --url _SITE --path $REVIEW_PATH
``

变量的名称和值只能使用整数和字

如果在 `gitlab-ci.yml` 文件的顶个变量，它是全局的，
这意味着它适用于所有工作。如果定义变量，则它可用
只到那个工作。

如果为特定流水线任务全局定义了同名变
[特定于流水线任务的变量覆盖全局变量](..les/README.md#cicd-variable-precedence)。

所有 YAML 定义的变量也设置为任何
[Docker 服务容器](../services/ind

你可以使用 [YAML 变量锚点](#yaml-or-variables)。

### 在手动流水线中预填充变量

> [引入](https://gitlab.com/gitlalab/-/issues/30101) GitLab 13.7。

使用 `value` 和 `description` 预先填充的流水线级（全局）变量](../pipelines/index.md#prefill-variables-in-manuapipe
当[手动运行流水线](../pipelines/ind-a-pipeline-manually)：

```yaml
变量：
  部署环境：
    value: "staging" # 默认部署到
    描述：“部署目标。如果需要，为‘canary’或‘production’。”
``

当你手动运行流水线时，你无法将作预填充。

### 使用变量配置跑步者行为

你可以使用 [CI/CD variables](../vREADME.md) 来配置运行程序如何处理 Git 请求：

- [`GIT_STRATEGY`](../runners/REAt-strategy)
- [`GIT_SUBMODULE_STRATEGY`](../rADME.md#git-submodule-strategy)
- [`GIT_CHECKOUT`](../runners/REAt-checkout)
- [`GIT_CLEAN_FLAGS`](../runners/#git-clean-flags)
- [`GIT_FETCH_EXTRA_FLAGS`](../ruDME.md#git-fetch-extra-flags)
- [`GIT_DEPTH`](../runners/READMEow-cloning)（浅克隆）
- [`GIT_CLONE_PATH`](../runners/Rcustom-build-directories)（自定义构建目录）
- [`TRANSFER_METER_FREQUENCY`](..README.md#artifact-and-cache-settings)（ `artifacts`/缓存表更新频率）
- [`ARTIFACT_COMPRESSION_LEVEL`](s/README.md#artifact-and-cache-settings)（ `artifacts`存档器压缩级别）
- [`CACHE_COMPRESSION_LEVEL`](../EADME.md#artifact-and-cache-settings)（缓存归档压缩级别）

你还可以使用变量来配置跑步者的次数
[尝试流水线任务执行的某些阶段](../runne.md#job-stages-attempts)。

## YAML 特定的功能

在你的 `.codechina-ci.yml` 文件中AML 特定的特性，比如锚点（`&`）、别名（`*`）、
和地图合并（`<<`）。使用这些功
`.codechina-ci.yml` 文件中的代码。

阅读有关各种 [YAML 功能](https://minutes.com/docs/yaml/) 的更多信息。

在大多数情况下，[`extends` 关键字s) 对用户更友好，你应该
尽可能使用它。

你可以使用 YAML 锚点来合并 YAML 。

### 锚

YAML 有一个叫做“锚点”的功能，你制
整个文档的内容。

使用锚点复制或继承属性。将锚点与作](#hide-jobs) 结合使用
为你的工作提供模板。当有重复的键
基于键执行反向深度合并。

使用 [`include`](#include) 时，文件使用 YAML 锚点
关键词。锚只在定义它们的文件中置
从不同的 YAML 文件，使用 [`!refer签](#reference-tags) 或
[`extends` 关键字](#extends)。

以下示例使用锚点和地图合并。它，
`test1` 和 `test2`，继承了 `.job_ 配置，每个
定义了自己的自定义“脚本”：

```yaml
.job_template: &job_configuration # 隐藏的 yaml 配置，它定义了一个名为“job_configuration”的锚点
  图片：红宝石：2.6
  服务：
    - postgres
    - Redis

测试1：
  <<: *job_configuration # 合并'job_configuration'别名的内容
  脚本：
    - test1 项目

测试2：
  <<: *job_configuration # 合并'job_configuration'别名的内容
  脚本：
    - 测试2项目
``

`&` 设置锚点的名称（`job_configuration`），`<<` 表示“合并
给定散列到当前的散列中，”并且 `*` 包括命名锚
（再次`job_configuration`）。这个例子的扩展版本是：

```yaml
.job_template：
  图片：红宝石：2.6
  服务：
    - postgres
    - Redis

测试1：
  图片：红宝石：2.6
  服务：
    - postgres
    - Redis
  脚本：
    - test1 项目

测试2：
  图片：红宝石：2.6
  服务：
    - postgres
    - Redis
  脚本：
    - 测试2项目
``

你可以使用锚点来定义两组服务。例如，`test:postgres`
和 `test:mysql` 共享 `.job_template` 中定义的 `script`，但使用不同的
`services`，在 `.postgres_services` 和 `.mysql_services` 中定义：

```yaml
.job_template: &job_configuration
  脚本：
    - 测试项目
  标签：
    - 开发

.postgres_services:
  服务：&postgres_configuration
    - postgres
    - 红宝石

.mysql_services:
  服务：&mysql_configuration
    - mysql
    - 红宝石

测试：postgres：
  <<: *job_configuration
  服务：*postgres_configuration
  标签：
    - postgres

测试：mysql：
  <<: *job_configuration
  服务：*mysql_configuration
``

扩展版本是：

```yaml
.job_template：
  脚本：
    - 测试项目
  标签：
    - 开发

.postgres_services:
  服务：
    - postgres
    - 红宝石

.mysql_services:
  服务：
    - mysql
    - 红宝石

测试：postgres：
  脚本：
    - 测试项目
  服务：
    - postgres
    - 红宝石
  标签：
    - postgres

测试：mysql：
  脚本：
    - 测试项目
  服务：
    - mysql
    - 红宝石
  标签：
    - 开发
``

你可以看到隐藏的流水线任务可以方便地用作模板，并且
`tags: [postgres]` 覆盖 `tags: [dev]`。

#### 脚本的 YAML 锚点

> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) 在 GitLab 12.5 中。

你可以将 [YAML 锚点](#anchors) 与 [script](#script)、[`before_script`](#before_script)、
和 [`after_script`](#after_script) 在多个流水线任务中使用预定义的命令：

```yaml
.some-script-before: &some-script-before
  - echo "先执行这个脚本"

.some-script: &some-script
  - echo "第二次执行这个脚本"
  - echo "也执行这个脚本"

.some-script-after: &some-script-after
  - echo "最后执行这个脚本"

工作1：
  之前_脚本：
    - *some-script-before
  脚本：
    - *一些脚本
    - echo "执行某事，仅针对这项工作"
  后脚本：
    - *some-script-after

工作2：
  脚本：
    - *some-script-before
    - *一些脚本
    - echo "执行其他操作，仅针对此工作"
    - *some-script-after
``

#### 变量的 YAML 锚点

使用 [YAML 锚点](#anchors) 和 `variables` 重复赋值
跨多个流水线任务的变量。你还可以在流水线任务时使用 YAML 锚点
需要一个特定的 `variables` 块，否则会覆盖全局变量。

以下示例显示如何在不影响的情况下覆盖 `GIT_STRATEGY` 变量
`SAMPLE_VARIABLE` 变量的使用：

```yaml
# 全局变量
变量：&全局变量
  SAMPLE_VARIABLE：sample_variable_value
  ANOTHER_SAMPLE_VARIABLE：another_sample_variable_value

# 一个必须设置 GIT_STRATEGY 变量但依赖于全局变量的流水线任务
job_no_git_strategy:
  阶段：清理
  变量：
    <<: *全局变量
    GIT_STRATEGY：无
  脚本：echo $SAMPLE_VARIABLE
``

### 隐藏工作

如果你想暂时禁用一个流水线任务，而不是注释掉所有的
定义流水线任务的行：

```yaml
# hidden_job:
＃ 脚本：
# - 运行测试
``

相反，你可以用一个点（`.`）开始它的名字，它不会被处理
亚搏体育应用 CI/CD。在下面的例子中，`.hidden_job` 被忽略：

```yaml
.hidden_job：
  脚本：
    - 运行测试
``

使用此功能忽略流水线任务，或使用
[YAML-specific features](#yaml-specific-features) 并转换隐藏流水线任务
成模板。

### `!reference` 标签

> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) 在 GitLab 13.9 中。

使用 `!reference` 自定义 YAML 标签从其他流水线任务中选择关键字配置
部分并在当前部分中重用它。与 [YAML 锚点](#anchors) 不同，你可以
使用 `!reference` 标签重用 [included](#include) 配置中的配置
文件也是如此。

在以下示例中，来自两个不同位置的 `script` 和一个 `after_script` 是
在 `test` 流水线任务中重用：

- `setup.yml`：

  ```yaml
  。设置：
    脚本：
      - echo 创建环境
  ``

-`.codechina-ci.yml`：

  ```yaml
  包括：
    - 本地：setup.yml

  。拆除：
    后脚本：
      - echo 删除环境

  测试：
    脚本：
      - !reference [.setup, script]
      - echo 运行我自己的命令
    后脚本：
      - !reference [.teardown, after_script]
  ``

在下面的例子中，`test-vars-1` 重用了 `.vars` 中的所有变量，而 `test-vars-2`
选择一个特定的变量并将其作为新的“MY_VAR”变量重用。

```yaml
.vars：
  变量：
    网址：“http://my-url.internal”
    IMPORTANT_VAR：“详细信息”

测试变量-1：
  变量：!reference [.vars, variables]
  脚本：
    - 打印环境

测试变量 2：
  变量：
    MY_VAR: !reference [.vars, variables, IMPORTANT_VAR]
  脚本：
    - 打印环境
``

你不能重复使用已经包含 `!reference` 标签的部分。只有一层
支持嵌套。

## 跳过流水线

要在不触发流水线的情况下推送提交，请添加 `[ci skip]` 或 `[skip ci]`，使用任何
大写，到你的提交消息。

或者，如果你使用 Git 2.10 或更高版本，请使用 `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd)。
`ci.skip` 推送选项不会跳过合并请求
流水线。

## 处理 Git 推送

GitLab 在以下情况下最多创建四个分支和标记流水线
在单个 `git push` 调用中推送多个更改。

此限制不会影响任何更新的合并请求流水线。
所有更新的合并请求都在使用时创建了一个流水线
[合并请求的流水线](../merge_request_pipelines/index.md)。

## 弃用的关键字

以下关键字已弃用。

### 全局定义的`types`

警告：
`types` 已弃用，可能会在未来版本中删除。
使用 [`stages`](#stages) 代替。

### 流水线任务定义的`type`

警告：
`type` 已弃用，可能会在未来版本之一中删除。
使用 [`stage`](#stage) 代替。

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

定义 `image`、`services`、`cache`、`before_script` 和
全局不推荐使用 `after_script`。可以删除支持
从未来的版本。

使用 [`default:`](#custom-default-keyword-values) 代替。例如：

```yaml
默认：
  图像：红宝石：3.0
  服务：
    - 码头工人：dind
  缓存：
    路径：[供应商/]
  之前_脚本：
    - 捆绑配置设置路径供应商/捆绑
    - 捆绑安装
  后脚本：
    - rm -rf tmp

GitCode / 帮助文档

yaml

.codechina-ci.yml文件的关键字参考

流水线任务关键字

不可用的流水线任务名称

自定义默认关键字值

全局关键字

stages

workflow

workflow:rules:variables

workflow:rules 模板

在分支流水线和合并请求流水线之间切换

include

include变量

include:local

include:local带通配符文件路径

include:file

一个项目中的多个文件

include:remote

include:template

嵌套引用

关键字详情

image

image:name

image:entrypoint

services

services:name

services:alias

services:entrypoint

services:command

script

before_script

after_script

Script 语法

stage

使用你自己的 Runner

.pre 和 .post

extends

合并请求详情

extends 和 include 一起使用

rules

Rules attributes

Rules 条款

避免重复的流水线

rules:if

rules 的通用 if 条款

rules:changes

rules:changes 中的变量

rules:exists

rules:allow_failure

rules:variables

复杂规则条款

only / except

only:refs / except:refs

only:variables / except:variables

only:changes / except:changes

only:kubernetes / except:kubernetes

needs

要求和限制

使用 needs 下载 artifacts

needs 跨项目下载 artifacts

同一项目中流水线间的 artifacts 下载

artifacts 下载到子流水线

可选 needs

tags

allow_failure

allow_failure:exit_codes

when

when:manual

when:delayed

environment

environment:name

environment:url

environment:on_stop

environment:action

environment:auto_stop_in

environment:kubernetes

environment:deployment_tier

动态环境

cache

`.codechina-ci.yml`文件的关键字参考

`stages`

`workflow`

`workflow:rules:variables`

`include`

`include`变量

`include:local`

`include:local`带通配符文件路径

`include:file`

`include:remote`

`include:template`

`image`

`image:name`

`image:entrypoint`

`services`

`services:name`

`services:alias`

`services:entrypoint`

`services:command`

`script`

`before_script`

`after_script`

`Script` 语法

`stage`

`.pre` 和 `.post`

`extends`

`extends` 和 `include` 一起使用

`rules`

`Rules` 条款

`rules:if`

`rules` 的通用 `if` 条款

`rules:changes`

`rules:changes` 中的变量

`rules:exists`

`rules:allow_failure`

`rules:variables`

`only` / `except`

`only:refs` / `except:refs`

`only:variables` / `except:variables`

`only:changes` / `except:changes`

`only:kubernetes` / `except:kubernetes`

`needs`

使用 `needs` 下载 `artifacts`

`needs` 跨项目下载 `artifacts`

同一项目中流水线间的 `artifacts` 下载

`artifacts` 下载到子流水线

可选 `needs`

`tags`

`allow_failure`

`allow_failure:exit_codes`

`when`

`when:manual`

`when:delayed`

`environment`

`environment:name`

`environment:url`

`environment:on_stop`

`environment:action`

`environment:auto_stop_in`

`environment:kubernetes`

`environment:deployment_tier`

`cache`

`cache:paths`

`cache:key`

`cache:key:files`

`cache:key:prefix`

`cache:untracked`

`cache:when`

`cache:policy`

`artifacts`

`dependencies`

`artifacts:exclude`

`artifacts:expire_in`

`artifacts:expose_as`

`artifacts:name`

`artifacts:paths`

`artifacts:public`

`artifacts:reports`

`artifacts:reports:cobertura`

`artifacts:reports:codequality`