CNB 文档

简体中文

English

简体中文

English

外观

配置文件

1989 字约 7 分钟

简介

云原生构建配置文件 (.cnb.yml) 用于定义在仓库发生特定事件（如推送新 Commit、创建 PR 等）时，云原生构建 服务是否应触发构建任务，以及构建任务中每个步骤的具体操作。

该配置文件采用 YAML 格式，与业界主流 CI 服务保持一致。

以下是一个简单且可用的 云原生构建 配置示例：

.cnb.yml
main: # 目标分支
  push: # 触发事件
    - docker:
        image: node:22 # 流水线执行环境，可使用任意 Docker 镜像
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test

此示例描述的流程如下：

  1. 当 main 分支收到 push 事件（即有新 Commit 推送至 main 分支）时触发构建。
  2. 选用 node:22 Docker 镜像作为任务执行环境。
  3. 依次执行 npm install 和 npm test 两个任务。

存放位置

云原生构建 约定的配置文件名为 .cnb.yml，应存放于代码仓库的根目录下，遵循“配置即代码” (Configuration as Code) 原则。

这意味着：

  • 配置文件的变更可通过 Pull Request (PR) 流程进行管理。
  • 在开源协作场景下，这一点尤为重要。
  • 构建流程与源代码一样接受版本控制，保持了相同的透明度和变更历史，易于追溯。

基本语法结构

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

数组形式 (推荐):

.cnb.yml
# 流水线结构：数组形式
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

对象形式:

.cnb.yml
# 流水线结构：对象形式
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

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

yaml-auto
yaml-auto

若在本地 VSCode 中开发，可按以下步骤配置：

  1. 安装 redhat.vscode-yaml 插件。

  2. 在 settings.json 配置文件中加入以下内容：

    {
  "yaml.schemas": {
    "https://docs.cnb.build/conf-schema-zh.json": ".cnb.yml"
  }
}

Jetbrains

jetbrains-yaml
jetbrains-yaml
  1. 打开 Settings / Preferences。
  2. 进入 Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings。
  3. 点击 + 添加新的映射。
  4. 设置一个名称。
  5. 在 Schema file or URL 中填入：https://docs.cnb.build/conf-schema-zh.json
  6. 添加映射文件名 .cnb.yml

配置复用

YAML Anchor (锚点)

YAML 锚点 (Anchor) 和引用 (Alias) 允许在同一文件内复用配置片段，避免重复，保持简洁

示例：

.cnb.yml
# 通用的 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"
        # 引用
        - *jobs

include

使用 include 关键字，可以在当前配置文件中导入当前仓库或其他仓库中的 YAML 文件。这有助于对大型配置进行拆分，提高可维护性和复用性。

使用示例

template.yml (被引用的文件)

template.yml
main:
  push:
    pipeline_2:
      env:
        ENV_KEY1: xxx
        ENV_KEY3: inner
      services:
        - docker
      stages:
        - name: echo
          script: echo 222

.cnb.yml (主配置文件)

.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 支持三种引入方式：

.cnb.yml
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 无法引用存储在密钥仓库中的文件，因为合并后的完整配置会展示在构建详情页中。

注意事项

  1. 支持嵌套 include，但最多不能超过 50 个配置文件。
  2. include 的本地文件路径相对于项目根目录。
  3. 不支持引用 git submodule 中的文件。
  4. 不支持跨文件使用 YAML 锚点 (&, *)。

reference (扩展标签)

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

注意事项

  1. !reference 支持嵌套引用，最多 10 层。
  2. 合并配置时，第一层的同名变量会被覆盖，不会合并。
  3. 解析顺序：先加载并合并所有 include 的文件和主文件 .cnb.yml，然后再解析 !reference 标签。合并过程基于原始文本，不感知引用解析后的值。

示例

a.yml
.val1:
  echo1: echo hello
.val2:
  friends:
    - one:
        name: tom
        say: !reference [.val1, echo1] # 引用本文件内的值
.cnb.yml
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}

进阶示例：复用整条流水线

.cnb.yml
.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 hello

VSCode 配置

为了在 VSCode 中编写带 !reference 标签的 YAML 文件时避免语法报错，需要进行如下配置：

在 settings.json 中添加：

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

提示

为避免系统解析时根据 schema 将顶层的变量名误认为分支名而产生错误提示，建议使用点号 (.) 开头命名用于 reference 的顶层变量（例如 .var）。

© 2025 cnb.cool