配置文件

1204 字约 4 分钟

简介

云原生构建配置文件(.cnb.yml)描述了当仓库发生一些事件时（有新的 Commit 被推送、有新的 PR 请求等）， 云原生构建 是否应该启动构建任务，如果启动构建的话，构建任务的每一步分别做什么。

云原生构建 的配置文件格式是 YAML，这一点与业界主流 CI 服务相同。

这是一个简单的、可工作的 云原生构建 配置文件：

main: # 触发分支
  push: # 触发事件
    - docker:
        image: node:22 # 流水线执行环境，可以指定任意docker镜像
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test

这个案例描述的流程如下：

声明了在 main 分支在收到 push 事件时（即有新的 Commit 推送到 main 分支）
会选择 Docker 镜像 node:22 作为执行环境
依次执行任务 npm install 和 npm test

存放位置

云原生构建 约定的配置文件命名为 .cnb.yml，存放于仓库根目录下，配置文件即代码。

这意味着，配置文件可以通过 PR 进行变更，开源协作场景下，这十分重要。

构建流程纳入版本管理，与源代码保持相同的透明度和变更流程，修改历史很容易追溯。

基本语法结构

配置文件的基本语法结构如下所示：

# 流水线结构：数组形式
main:
  push:
    # main 分支 - push 事件包含两条流水线：push-pipeline1 和 push-pipeline2
    - name: push-pipeline1 # 流水线名称，可省略
      stages:
        - name: job1
          script: echo 1
    - name: push-pipeline2 # 流水线名称，可省略
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # main 分支 - pull_request 事件包含两条流水线：pr-pipeline1 和 pr-pipeline2
    - name: pr-pipeline1 # 流水线名称，可省略
      stages:
        - name: job1
          script: echo 1
    - name: pr-pipeline2 # 流水线名称，可省略
      stages:
        - name: job2
          script: echo 2

等价与以下写法：

# 流水线结构：对象形式
main:
  push:
    # main 分支 - push 事件包含两条流水线：push-pipeline1 和 push-pipeline2
    push-pipeline1: # 流水线名称，必须唯一
      stages:
        - name: job1
          script: echo 1
    push-pipeline2: # 流水线名称，必须唯一
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # main 分支 - pull_request 事件包含两条流水线：pr-pipeline1 和 pr-pipeline2
    pr-pipeline1: # 流水线名称，必须唯一
      stages:
        - name: job1
          script: echo 1
    pr-pipeline2: # 流水线名称，必须唯一
      stages:
        - name: job2
          script: echo 3

其中 main 表示分支名称， push 和 pull_request 表示触发事件。

一个事件包含多个 pipeline，支持数组和对象两种形式，并发执行。

一个 pipeline 包含一组顺序执行的任务，在同一个构建环境（物理机、虚拟机或 Docker 容器）中执行。

详细语法说明可参考：流水线语法

配置文件版本选择

因为配置文件是在项目仓库中，受到 Git 仓库版本控制的，所以配置文件自然也会有多个版本，在某次构建中，使用哪个版本的配置文件，应该是开发者必须了解的信息。幸运的是， 云原生构建 的机制是非常符合直觉的，在绝大多数场景下，开发者都不需要额外关心这件事。

下面列举在各个事件中，云原生构建 是如何选择使用哪个版本配置文件中的内容，需要额外关注的是 pull_request 事件，它的选择相对复杂一些：

对于 push、branch.create、vscode 事件，会从当前分支最新 Commit 节点读取配置文件。
对于 auto_tag、branch.delete、issue.* 会从默认分支读取配置文件。
对于 tag_push、tag_deploy.* 事件，会从当前 Tag 读取配置文件。
对于 pull_request、pull_request.update、pull_request.approved、pull_request.changes_requested 事件，有源分支和目标分支，取预合并后的配置文件。
对于 pull_request.merged 事件，取合并后的配置文件。
对于 pull_request.target、pull_request.mergeable 事件，取合并前目标分支的配置文件。
api_trigger 自定义事件，可以指定版本，cnb:apply 则限制为当前流水线对应版本。
web_trigger 自定义事件，会从对应分支、Tag 读取配置文件，参考具体应用场景。
定时任务事件，从指定的分支读取配置文件。

语法检查和自动补全

VSCode

推荐使用云原生开发书写配置文件，因为原生支持语法检查和自动补全，效果如下：

本地开发配置方法，以 VSCode 为例：

先安装 redhat.vscode-yaml 插件，然后在 settings.json 中加入以下配置：

Jetbrains

「Settings」「Languages & Frameworks」「Schemas and DTDs」「JSON Schema Mappings」
点击新增按钮，设置「Name」（名称随意填写）
设置「Schema file or URL」
「Add mapping for a file」