CNB 文档

简体中文

English

简体中文

English

外观

配置文件

复制页面

942 字约 3 分钟

简介

云原生构建配置文件用于定义代码仓库在特定事件（如推送新 Commit、创建 Pull Request 等）触发时，云原生构建服务是否执行构建任务，以及构建任务中每个步骤的具体操作。

配置文件说明

  1. 配置文件规范

    • 文件名为 .cnb.yml，存放于代码仓库根目录，遵循“配置即代码” (Configuration as Code) 原则。
    • 配置变更可通过 Pull Request (PR) 流程管理，特别适合开源协作场景。
    • 构建流程与源代码同步版本控制，确保透明度和变更历史可追溯。

  2. YAML 格式优势

    • 支持嵌套结构和键值对，清晰表达复杂配置逻辑。
    • 易于扩展和修改，适应动态需求，支持注释提升协作效率。
    • 语法简洁严格，减少配置错误，文件轻量，加载和解析高效。

如需了解更多，请参考语法手册和触发规则。

示例配置

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

.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
# 流水线结构：数组形式
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.cool/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.cool/conf-schema-zh.json
  6. 添加映射文件名 .cnb.yml

© 2026 cnb.cool