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

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

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

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

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

GitCode / 帮助文档

yaml

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