配置文件

简介

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

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

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

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

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

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

存放位置

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

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

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

基本语法结构

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

 1# 流水线结构：数组形式
 2main:
 3  push:
 4    # main 分支 - push 事件包含两条流水线：push-pipeline1 和 push-pipeline2
 5    - name: push-pipeline1 # 流水线名称，可省略
 6      stages:
 7        - name: job1
 8          script: echo 1
 9    - name: push-pipeline2 # 流水线名称，可省略
10      stages:
11        - name: job2
12          script: echo 2
13
14  pull_request:
15    # main 分支 - pull_request 事件包含两条流水线：pr-pipeline1 和 pr-pipeline2
16    - name: pr-pipeline1 # 流水线名称，可省略
17      stages:
18        - name: job1
19          script: echo 1
20    - name: pr-pipeline2 # 流水线名称，可省略
21      stages:
22        - name: job2
23          script: echo 2

等价与以下写法：

 1# 流水线结构：对象形式
 2main:
 3  push:
 4    # main 分支 - push 事件包含两条流水线：push-pipeline1 和 push-pipeline2
 5    push-pipeline1: # 流水线名称，必须唯一
 6      stages:
 7        - name: job1
 8          script: echo 1
 9    push-pipeline2: # 流水线名称，必须唯一
10      stages:
11        - name: job2
12          script: echo 2
13
14  pull_request:
15    # main 分支 - pull_request 事件包含两条流水线：pr-pipeline1 和 pr-pipeline2
16    pr-pipeline1: # 流水线名称，必须唯一
17      stages:
18        - name: job1
19          script: echo 1
20    pr-pipeline2: # 流水线名称，必须唯一
21      stages:
22        - name: job2
23          script: echo 3

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

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

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

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

配置文件版本选择

同代码版本选择

语法检查和自动补全

VSCode

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

yaml-auto

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

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

1"yaml.schemas": {
2  "https://docs.cnb.cool/conf-schema-zh.json": ".cnb.yml"
3},

Jetbrains

yaml-auto

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

1https://docs.cnb.cool/conf-schema-zh.json

配置复用

anchor

在 YAML 中，锚点（Anchor）和引用（Alias）允许同一个文件中复用配置，从而避免重复并保持文件的简洁。

示例：

 1# .cnb.yml
 2# 通用的流水线配置
 3.pipeline-config: &pipeline-config
 4  stages:
 5    - echo "do something"
 6main:
 7  push:
 8    # 引用 pipeline-config
 9    - *pipeline-config
10dev:
11  push:
12    # 引用 pipeline-config
13    - *pipeline-config

include

利用 include 参数，可以在当前文件导入当前仓库或其他仓库上的文件。依此可以对配置文件进行拆分，方便复用和维护。

使用示例

template.yml

 1# template.yml
 2main:
 3  push:
 4    pipeline_2:
 5      env:
 6        ENV_KEY1: xxx
 7        ENV_KEY3: inner
 8      services:
 9        - docker
10      stages:
11        - name: echo
12          script: echo 222

.cnb.yml

 1# .cnb.yml
 2include:
 3  - https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/template.yml
 4
 5main:
 6  push:
 7    pipeline_1:
 8      stages:
 9        - name: echo
10          script: echo 111
11    pipeline_2:
12      env:
13        ENV_KEY2: xxx
14        ENV_KEY3: outer
15      stages:
16        - name: echo
17          script: echo 333

合并后的配置

 1main:
 2  push:
 3    pipeline_1: # key不存在，合并时新增
 4      stages:
 5        - name: echo
 6          script: echo 111
 7    pipeline_2:
 8      env:
 9        ENV_KEY1: xxx
10        ENV_KEY2: xxx # key不存在，合并时新增
11        ENV_KEY3: outer # 同名 key， 合并时覆盖
12      services:
13        - docker
14      stages: # 数组在合并时，追加
15        - name: echo
16          script: echo 222
17        - name: echo
18          script: echo 333

语法说明

 1include:
 2  # 1、可直接传入配置文件路径
 3  - "https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/template.yml"
 4  - "template.yml"
 5  # 2、可传入一个对象。
 6  # path: 配置文件路径
 7  # ignoreError：未读取到配置文件是否抛出错误。true 不抛出错误；false 抛出错误。默认为 false
 8  - path: "template1.yml"
 9    ignoreError: true
10  # 3、可传入一个对象
11  # config: 传入 yaml 配置
12  - config:
13      main:
14        push:
15          - stages:
16              - name: echo
17                script: echo "hello world"

合并规则

不同文件的流水线配置合并规则：

数组(Array)和数组(Array)合并：子元素追加
对象(Map)和对象(Map)合并：同名 key 覆盖
数组(Array)和对象(Map)合并：仅保留数组
对象(Map)和数组(Array)合并：仅保留数组

引用配置文件权限控制参考配置文件引用鉴权

:::tip 合并后的流水线配置会展示在构建详情页，与密钥仓库内容保护的理念不符，include 无法引用密钥仓库文件。 :::

:::tip

本地的 .cnb.yml 会覆盖 include 中的配置，include 数组中后面的配置会覆盖前面的配置。
支持嵌套 include，include 的本地文件路径相对于项目根目录。
最多支持 include 50个配置文件。
不支持引用 submodule 中的文件。
不支持跨文件使用 YAML 锚点功能。

:::

reference

YAML 不支持跨文件引用，云原生构建 通过扩展 YAML 自定义标签 reference 实现按属性路径引用变量值，可结合 include 跨文件复用配置。

:::tip

第一层同名变量会被覆盖，不会合并。本地的 .cnb.yml 会覆盖 include 中的变量，include 数组中后面的变量会覆盖前面的变量。
reference 支持嵌套引用，最多 10 层。

:::

示例

a.yml

1.val1:
2  echo1: echo hello
3.val2:
4  friends:
5    - one:
6      name: tom
7      say: !reference [.val1, echo1]

.cnb.yml

 1include:
 2  - ./a.yml
 3.val3:
 4  size: 100
 5main:
 6  push:
 7    - stages:
 8        - name: echo hello
 9          script: !reference [.val2, friends, "0", say]
10        - name: echo size
11          env:
12            SIZE: !reference [".val3", "size"]
13          script: echo my size ${SIZE}

解析后相当于：

1main:
2  push:
3    - stages:
4        - name: echo hello
5          script: echo hello
6        - name: echo size
7          env:
8            SIZE: 100
9          script: echo my size ${SIZE}

进阶示例

可以将流水线作为整体配置引用：

1.common-pipeline:
2  - stages:
3      - name: echo
4        script: echo hello
5
6main:
7  push: !reference [.common-pipeline]
8test:
9  push: !reference [.common-pipeline]

解析后相当于：

 1main:
 2  push:
 3    - stages:
 4        - name: echo
 5          script: echo hello
 6test:
 7  push:
 8    - stages:
 9        - name: echo
10          script: echo hello

VSCode 配置

安装 VSCode YAML 插件后，为了在 VSCode 编写带自定义标签 reference 的 YAML 文件时不报错，需要如下配置：

setting.json

1{
2  "yaml.customTags": ["!reference sequence"]
3}

:::tip 为避免编写时 YAML 插件根据 Schema 把第一层变量名当做分支名，有错误提示，reference 所在的第一层变量名可用 . 开头，如：.var。 :::