配置文件

773 字约 3 分钟

配置文件 介绍云原生构建配置文件 .cnb.yml 的格式规范与编写方式。

使用场景：为仓库接入云原生构建时使用——例如让推送新 Commit 或创建 Pull Request 时自动执行构建任务，或按分支、事件组织多套流水线。

简介

云原生构建配置文件定义代码仓库在特定事件（如推送新 Commit、创建 Pull Request）触发时执行的构建任务及各步骤操作。

配置文件说明

配置文件规范
- 文件名为 .cnb.yml，存放于代码仓库根目录，遵循「配置即代码」原则。
- 配置变更可通过 Pull Request 流程管理，适合开源协作。
- 构建流程与源代码同步版本控制，确保透明度和变更可追溯。
YAML 格式优势
- 支持嵌套结构和键值对，清晰表达复杂配置。
- 易于扩展和修改，适应动态需求，支持注释提升协作效率。

更多详情请参考语法手册和触发规则。

示例配置

以下是一个云原生构建配置示例：

.cnb.yml
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test

示例流程说明

触发条件：当 main 分支收到 push 事件（即有新 Commit 推送至 main 分支）时，触发构建任务。
执行环境：使用 node:22 Docker 镜像作为任务执行环境。
任务步骤：
- 执行 npm install 安装依赖。
- 执行 npm test 运行测试。

基本语法结构

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

.cnb.yml
main:
  push:
    - name: push-pipeline1
      stages:
        - script: echo 1
    - name: push-pipeline2
      stages:
        - script: echo 2

一个事件下可包含多条 pipeline，支持数组（推荐）和对象两种写法，多条 pipeline 会并发执行。其中：

main 表示分支名称
push、pull_request 表示触发事件
一条 pipeline 包含一组顺序执行的 stages，在同一个构建环境中运行

更详细的语法说明参阅：语法手册

配置文件版本选择

配置文件版本的选择规则与代码版本选择相同。

语法检查和自动补全

VSCode

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

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

安装 redhat.vscode-yaml 插件。

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

{
  "yaml.schemas": {
    "https://docs.cnb.build/conf-schema-zh.json": ".cnb.yml",
    "https://docs.cnb.build/tag-deploy-schema-zh.json": ".cnb/tag_deploy.yml",
    "https://docs.cnb.build/web-trigger-schema-zh.json": ".cnb/web_trigger.yml",
    "https://docs.cnb.build/settings-schema-zh.json": ".cnb/settings.yml",
    "https://docs.cnb.build/code-security-conf-schema-zh.json": ".cnb/security/code_scan_config.yml"
  }
}

JetBrains

打开 Settings / Preferences。
进入 Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings。
点击 + 添加新的映射，共添加五条：
- https://docs.cnb.build/conf-schema-zh.json → .cnb.yml
- https://docs.cnb.build/tag-deploy-schema-zh.json → .cnb/tag_deploy.yml
- https://docs.cnb.build/web-trigger-schema-zh.json → .cnb/web_trigger.yml
- https://docs.cnb.build/settings-schema-zh.json → .cnb/settings.yml
- https://docs.cnb.build/code-security-conf-schema-zh.json → .cnb/security/code_scan_config.yml