配置文件
1989 字约 7 分钟
简介
云原生构建配置文件 (.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 分支)时触发构建。 - 选用
node:22Docker 镜像作为任务执行环境。 - 依次执行
npm install和npm test两个任务。
存放位置
云原生构建 约定的配置文件名为 .cnb.yml,应存放于代码仓库的根目录下,遵循“配置即代码” (Configuration as Code) 原则。
这意味着:
- 配置文件的变更可通过 Pull Request (PR) 流程进行管理。
- 在开源协作场景下,这一点尤为重要。
- 构建流程与源代码一样接受版本控制,保持了相同的透明度和变更历史,易于追溯。
基本语法结构
配置文件的基本结构如下所示:
数组形式 (推荐):
# 流水线结构:数组形式
main:
push:
# main 分支的 push 事件包含两条流水线
- name: push-pipeline1 # 流水线名称,可选
stages:
- name: job1
script: echo 1
- name: push-pipeline2 # 流水线名称,可选
stages:
- name: job2
script: echo 2
pull_request:
# main 分支的 pull_request 事件包含两条流水线
- name: pr-pipeline1 # 流水线名称,可选
stages:
- name: job1
script: echo 1
- name: pr-pipeline2 # 流水线名称,可选
stages:
- name: job2
script: echo 2对象形式:
# 流水线结构:对象形式
main:
push:
# main 分支的 push 事件包含两条流水线
push-pipeline1: # 流水线名称,必须唯一
stages:
- name: job1
script: echo 1
push-pipeline2: # 流水线名称,必须唯一
stages:
- name: job2
script: echo 2
pull_request:
# main 分支的 pull_request 事件包含两条流水线
pr-pipeline1: # 流水线名称,必须唯一
stages:
- name: job1
script: echo 1
pr-pipeline2: # 流水线名称,必须唯一
stages:
- name: job2
script: echo 2其中:
main表示分支名称。push和pull_request表示触发事件。- 一个事件下可包含多条
pipeline(支持数组和对象两种写法),这些 pipeline 会并发执行。 - 一条
pipeline包含一组顺序执行的stages,它们在同一个构建环境(物理机、虚拟机或 Docker 容器)中运行。
更详细的语法说明请参阅:语法手册
配置文件版本选择
配置文件版本的选择规则与代码版本选择相同。
语法检查和自动补全
VSCode
推荐使用 云原生开发 环境编写配置文件,其原生支持语法检查和自动补全,效果如下:

若在本地 VSCode 中开发,可按以下步骤配置:
安装
redhat.vscode-yaml插件。在
settings.json配置文件中加入以下内容:{ "yaml.schemas": { "https://docs.cnb.build/conf-schema-zh.json": ".cnb.yml" } }
Jetbrains

- 打开
Settings/Preferences。 - 进入
Languages & Frameworks->Schemas and DTDs->JSON Schema Mappings。 - 点击
+添加新的映射。 - 设置一个名称。
- 在
Schema file or URL中填入:https://docs.cnb.build/conf-schema-zh.json - 添加映射文件名
.cnb.yml
配置复用
YAML Anchor (锚点)
YAML 锚点 (Anchor) 和引用 (Alias) 允许在同一文件内复用配置片段,避免重复,保持简洁
示例:
# 通用的 jobs
.jobs: &jobs
- echo "do something"
- echo "do something other"
main:
push:
- stages:
- echo "in main push"
# 引用
- *jobs
pull_request:
- stages:
- echo "in main pull_request"
# 引用
- *jobs
dev:
push:
- stages:
- echo "in dev push"
# 引用
- *jobsinclude
使用 include 关键字,可以在当前配置文件中导入当前仓库或其他仓库中的 YAML 文件。这有助于对大型配置进行拆分,提高可维护性和复用性。
使用示例
template.yml (被引用的文件)
main:
push:
pipeline_2:
env:
ENV_KEY1: xxx
ENV_KEY3: inner
services:
- docker
stages:
- name: echo
script: echo 222.cnb.yml (主配置文件)
include:
- https://cnb.build/<your-repo-slug>/-/blob/main/xxx/template.yml
main:
push:
pipeline_1:
stages:
- name: echo
script: echo 111
pipeline_2:
env:
ENV_KEY2: xxx # 新增环境变量
ENV_KEY3: outer # 覆盖 template.yml 中的 ENV_KEY3
stages:
- name: echo
script: echo 333 # 新增步骤合并后的等效配置:
main:
push:
pipeline_1: # key不存在,合并时新增
stages:
- name: echo
script: echo 111
pipeline_2: # key已存在,合并内容
env: # 对象合并:同名键覆盖,新键添加
ENV_KEY1: xxx # 来自 template.yml
ENV_KEY2: xxx # 来自 .cnb.yml (新增)
ENV_KEY3: outer # 来自 .cnb.yml (覆盖)
services: # 数组合并:追加元素
- docker # 来自 template.yml
stages: # 数组合并:追加元素
- name: echo # 来自 template.yml
script: echo 222
- name: echo # 来自 .cnb.yml
script: echo 333语法说明
include 支持三种引入方式:
include:
# 1. 直接传入配置文件路径 (字符串)
- "https://cnb.build/<your-repo-slug>/-/blob/main/xxx/template.yml"
- "template.yml" # 相对路径(相对于仓库根目录)
# 2. 传入对象,提供更多控制
# path: 配置文件路径
# ignoreError: 未找到文件时是否报错。true-忽略错误;false-报错(默认)
- path: "template1.yml"
ignoreError: true
# 3. 直接传入内联的 YAML 配置对象
- config:
main:
push:
- stages:
- name: echo
script: echo "hello world"合并规则
不同文件间的配置按以下规则合并:
- 数组 + 数组: 合并所有元素(追加)。
- 对象 + 对象: 合并键,同名键的值会被覆盖。
- 数组 + 对象 或 对象 + 数组: 最终结果仅为数组(对象被忽略)。
- 合并顺序:本地
.cnb.yml配置覆盖include引入的配置;include数组中后面的配置覆盖前面的配置。
权限说明: 出于安全考虑,与敏感信息保护原则一致,include 无法引用存储在密钥仓库中的文件,因为合并后的完整配置会展示在构建详情页中。
注意事项
- 支持嵌套 include,但最多不能超过 50 个配置文件。
- include 的本地文件路径相对于项目根目录。
- 不支持引用 git submodule 中的文件。
- 不支持跨文件使用 YAML 锚点 (
&,*)。
reference (扩展标签)
YAML 标准不支持跨文件引用。云原生构建 通过扩展的 !reference 自定义标签实现了按属性路径引用值的功能,可与 include 结合实现跨文件配置复用。
注意事项
!reference支持嵌套引用,最多 10 层。- 合并配置时,第一层的同名变量会被覆盖,不会合并。
- 解析顺序:先加载并合并所有
include的文件和主文件.cnb.yml,然后再解析!reference标签。合并过程基于原始文本,不感知引用解析后的值。
示例
.val1:
echo1: echo hello
.val2:
friends:
- one:
name: tom
say: !reference [.val1, echo1] # 引用本文件内的值include:
- ./a.yml # 引入 a.yml
.val3:
size: 100
main:
push:
- stages:
- name: echo hello
# 跨文件引用 a.yml 中的值
script: !reference [.val2, friends, "0", say]
- name: echo size
env:
# 引用本文件 .cnb.yml 中的值
SIZE: !reference [".val3", "size"]
script: echo my size ${SIZE}解析后的等效配置:
main:
push:
- stages:
- name: echo hello
script: echo hello # 解析后的值
- name: echo size
env:
SIZE: 100 # 解析后的值
script: echo my size ${SIZE}进阶示例:复用整条流水线
.common-pipeline:
- stages:
- name: echo
script: echo hello
main:
push: !reference [.common-pipeline] # 引用整条流水线
test:
push: !reference [.common-pipeline] # 引用整条流水线解析后的等效配置:
main:
push:
- stages:
- name: echo
script: echo hello
test:
push:
- stages:
- name: echo
script: echo helloVSCode 配置
为了在 VSCode 中编写带 !reference 标签的 YAML 文件时避免语法报错,需要进行如下配置:
在 settings.json 中添加:
{
"yaml.customTags": ["!reference sequence"]
}提示
为避免系统解析时根据 schema 将顶层的变量名误认为分支名而产生错误提示,建议使用点号 (.) 开头命名用于 reference 的顶层变量(例如 .var)。