配置文件

CNB 流水线通过 .cnb.yml 配置文件定义自动化构建流程。

基本结构

CNB 流水线采用层级结构，从外到内依次是：

触发分支：指定哪些分支的代码会触发流水线，例如 main、dev。
触发事件：指定什么操作会触发流水线，例如 push、pull_request。
Pipeline（流水线）：一次完整的构建流程，包含多个阶段。
Stage（阶段）：流水线中的一个步骤，可包含一个或多个任务。
Job（任务）：最小的执行单元，执行具体的命令或插件。

执行流程示意

触发分支 (main)
└─ 触发事件 (push)
   ├─ Pipeline (流水线)
   │   └─ Stage（阶段）
   │       └─ Job（任务）
   └─ Pipeline (流水线)
       └─ Stage（阶段）
           └─ Job（任务）

完整示例

.cnb.yml

yaml

main: # 触发分支：在 main 分支上触发
  push: # 触发事件：代码推送时触发
    - name: pipeline-1 # 流水线名称
      stages:
        - name: stage-1 # 阶段名称
          jobs:
            - name: job-1 # 任务名称
              script: echo "in pipeline-1"
    - name: pipeline-2 # 流水线名称
      stages:
        - name: stage-1 # 阶段名称
          jobs:
            - name: job-1 # 任务名称
              script: echo "in pipeline-2"

也支持通过对象的形式声明多个流水线： .cnb.yml

yaml

main: # 触发分支
  push: # 触发事件
    pipeline-1: # 流水线标识
      stages:
        - name: stage-1
          jobs:
            - name: job-1
              script: echo "Hello World"
    pipeline-2: # 流水线标识
      stages:
        - name: stage-1
          jobs:
            - name: job-1
              script: echo "Hello World"

触发分支

作用：指定哪些分支的代码会触发流水线。

支持模式

精确匹配：精确匹配分支名，例如 main、dev、release。
通配符匹配：使用 glob 语法匹配，例如 feature/*、hotfix/*。
兜底匹配：匹配所有未明确指定的分支，使用 $。

分支匹配示例

.cnb.yml

yaml

# 只在 main 分支触发
main:
  push:
    - stages:
        - echo "main branch"

# 匹配所有 feature 开头的分支
feature/*:
  push:
    - stages:
        - echo "feature branch"

# 兜底：匹配其他所有分支
$:
  push:
    - stages:
        - echo "other branches"

触发事件

作用：指定什么操作会触发流水线执行。

常用事件

push：代码推送到分支时触发。
pull_request：创建或更新 Pull Request 时触发。
tag_push：推送标签时触发。
branch.delete：删除分支时触发。

触发事件示例

.cnb.yml

yaml

main:
  # 代码推送时执行测试
  push:
    - stages:
        - npm test

  # PR 时执行代码检查
  pull_request:
    - stages:
        - npm run lint

Pipeline

Pipeline 表示一个流水线，包含一个或多个阶段 Stage，每个 Stage 依次执行。

配置项概览

Pipeline 支持的配置项包括：name、runner、docker、git、services、env、imports、label、stages、failStages、endStages、ifNewBranch、ifModify、breakIfModify、retry、allowFailure、lock、sandbox。

配置项详细说明

name

类型：String
指定流水线名，默认为 pipeline。多条并行流水线的默认名称依次为 pipeline、pipeline-1、pipeline-2。

runner

类型：Object
指定构建节点相关参数。
子参数：
- tags (String | Array<String>)：指定使用具备哪些标签的构建节点。
- cpus (Number)：指定构建需使用的 cpu 核数（内存 = CPU 核数 × 2 GiB）。

示例： .cnb.yml

yaml

main:
  push:
    - runner:
        tags: cnb:arch:amd64
      stages:
        - name: uname
          script: uname -a

docker

类型：Object
指定 docker 相关的参数。
子参数：
- image：当前 Pipeline 的环境镜像。
- build：指定一个 Dockerfile，构建一个临时镜像。
- devcontainer：指定 devcontainer.json 文件所在路径。
- volumes：声明数据卷，用于缓存场景。

优先级：build > devcontainer > image。

docker.image

类型：Object | String
指定当前 Pipeline 的环境镜像。
属性：
- image.name：镜像名，如 node:20。
- image.dockerUser：指定 Docker 用户名。
- image.dockerPassword：指定 Docker 用户密码。

示例： .cnb.yml

yaml

main:
  push:
    - docker:
        image: node:20
      stages:
        - name: show version
          script: node -v

docker.build

类型：Object | String
指定一个 Dockerfile，构建一个临时镜像。
参数：
- build.dockerfile：Dockerfile 路径。
- build.target：对应 docker build 中的 --target 参数。
- build.by：声明缓存构建过程中依赖的文件列表。
- build.versionBy：用于版本控制。
- build.buildArgs：在 build 时插入额外的构建参数。
- build.ignoreBuildArgsInVersion：版本计算是否忽略 buildArgs。
- build.sync：是否等待 docker push 成功后才继续。

示例： .cnb.yml

yaml

main:
  push:
    - docker:
        build: ./image/Dockerfile
      stages:
        - stage1
        - stage2

docker.devcontainer

类型：String
指定 devcontainer.json 文件所在路径。
当前支持的属性：image、build.dockerfile、build.context、build.args、build.target。

docker.volumes

类型：Array<String> | String
声明数据卷，用于缓存场景。
支持的格式：
- <group>:<path>:<type>
- <path>:<type>
- <path>
数据卷类型：
- read-write (rw)：读写。
- read-only (ro)：只读。
- copy-on-write (cow)：读写，变更在流水线成功后被合并（默认）。
- copy-on-write-read-only：只读，变更在流水线结束后丢弃。
- data：创建临时数据卷，流水线结束时自动清理。

示例： .cnb.yml

yaml

main:
  push:
    - docker:
        image: node:20
        volumes:
          - /data/config:read-only
          - /data/mydata:read-write
          - /root/.npm
          - main:/root/.gradle:copy-on-write
      stages:
        - stage1
        - stage2

git

类型：Object
提供 Git 仓库相关配置。
子参数：
- enable (Boolean)：是否拉取代码。
- submodules：指定是否要拉取子项目。
- lfs：指定是否要拉取 LFS 文件。

示例： .cnb.yml

yaml

main:
  push:
    - git:
        enable: true
        submodules: true
      stages:
        - name: echo
          script: echo "hello world"

services

类型：Array<String> | Array<Object>
用于声明构建时需要的服务，格式：name:[version]。
支持的服务：docker、vscode。

service:docker

用于开启 dind 服务。示例： .cnb.yml

yaml

main:
  push:
    - services:
        - docker
      docker:
        image: alpine
      stages:
        - name: docker info
          script:
            - docker info
            - docker ps

service:vscode

需要云原生开发时声明。示例： .cnb.yml

yaml

$:
  vscode:
    - services:
        - vscode
        - docker
      docker:
        image: alpine
      stages:
        - name: uname
          script: uname -a

env

类型：Object
声明环境变量，对当前 Pipeline 内的所有非插件任务生效。示例： .cnb.yml

yaml

main:
  push:
    - services:
        - docker
      env:
        some_key: some_value
      stages:
        - name: some job
          script: echo "$some_value"

imports

类型：Array<String> | String
指定文件路径作为环境变量来源，作用同 env。
文件解析规则：支持 YAML、JSON、证书文件和其他文本文件。
同名 key 优先级：数组中后面的覆盖前面的，env 中的参数会覆盖 imports 文件中的。

label

类型：Object
为流水线指定标签，可用于后续流水线记录筛选等功能。

stages

类型：Array<Stage|Job>
定义一组阶段任务，每个阶段串行运行。

failStages

类型：Array<Stage|Job>
定义一组失败阶段任务。当正常流程失败，会依次执行此阶段任务。

endStages

类型：Array<Stage|Job>
定义流水线结束阶段执行的一组任务。当流水线 stages/failStages 执行完，流水线结束前，会依次执行此阶段任务。

ifNewBranch

类型：Boolean
默认值：false
为 true 表示当前分支属于新分支时，才执行此 Pipeline。

ifModify

类型：Array<String> | String
指定只有相应文件变动时，才执行此 Pipeline。是一个 glob 表达式字符串或字符串数组。

示例：

yaml

# 当修改文件列表中包含 a.js 或者 b.js
ifModify:
  - a.js
  - b.js

# 当修改文件列表中包含有 js 后缀的文件时
ifModify:
  - "**/*.js"

# 反向匹配，排除目录 legacy 和排除所有 Markdown 文件
ifModify:
  - "**"
  - "!(legacy/**)"
  - "!(**/*.md)"

breakIfModify

类型：Boolean
默认值：false
Job 执行前，如果源分支已更新，则终止构建。

retry

类型：Number
默认值：0
失败重试次数，0 表示不重试。

allowFailure

类型：Boolean
默认值：false
是否允许当前流水线失败。

lock

类型：Object | Boolean
给 pipeline 设置锁。
参数：
- key：自定义锁名。
- expires：锁过期时间（秒）。
- timeout：超时时间（秒）。
- cancel-in-progress：是否终止占用锁或等待锁的流水线。
- wait：锁被占用是否等待。
- cancel-in-wait：是否终止正在等待锁的流水线。

示例： .cnb.yml

yaml

main:
  push:
    - lock: true
      stages:
        - name: stage1
          script: echo "stage1"

sandbox

类型：Boolean
是否开启沙箱模式。设为 true 时，环境变量 CNB_TOKEN 将无效。

Stage

类型：Job | Object<name: Job>
Stage 表示流水线中的一个阶段，可包含一个或多个 Job。

配置项概览

Stage 支持的配置项包括：name、ifNewBranch、ifModify、if、env、imports、retry、lock、image、jobs。

结构说明

单个 Job

当 Stage 只有一个 Job 时，可省略 Stage 层级，直接声明 Job。

yaml

stages:
  - name: stage1
    jobs:
      - name: job A
        script: echo hello

可以简化为：

yaml

- stages:
  - name: job A
    script: echo hello

当 Job 为字符串时，可视作脚本任务：

yaml

- stages:
  - echo hello

串行 Job

当 jobs 为数组时，这组 Job 会按顺序串行执行。

yaml

stages:
  - name: install
    jobs:
      - name: job1
        script: echo "job1"
      - name: job2
        script: echo "job2"

并行 Job

当 jobs 为对象时，这组 Job 会并行执行。

yaml

stages:
  - name: install
    jobs:
      job1:
        script: echo "job1"
      job2:
        script: echo "job2"

配置项说明

name

类型：String
阶段名称。

ifNewBranch

类型：Boolean
默认值：false
为 true 表示当前分支属于新分支时，才执行此 Stage。

ifModify

类型：Array<String> | String
指定只有相应文件变动时，才执行此 Stage。

if

类型：Array<String> | String
指定一个 shell 脚本，当脚本退出码为 0 时，执行此 Stage。

示例： .cnb.yml

yaml

main:
  push:
    - env:
        IS_NEW: true
      stages:
        - name: is new
          if: |
            [ "$IS_NEW" = "true" ]
          script: echo is new
        - name: is not new
          if: |
            [ "$IS_NEW" != "true" ]
          script: echo not new

env

类型：Object
声明环境变量，仅对当前 Stage 生效。

imports

类型：Array<String> | String
从文件导入环境变量，仅对当前 Stage 生效。

retry

类型：Number
默认值：0
失败重试次数。

lock

类型：Boolean | Object
给 Stage 设置锁。

示例： .cnb.yml

yaml

main:
  push:
    - stages:
        - name: stage1
          lock: true
          jobs:
            - name: job1
              script: echo "job1"

Stage.image

类型：Object | String
指定当前 Stage 的环境镜像。

jobs

类型：Array<Job> | Object<name,Job>
定义一组任务。数组形式为串行执行，对象形式为并行执行。

Job

Job（任务）是最小的执行单元，主要分为脚本任务、插件任务和内置任务三种类型。

配置文件 ​

基本结构 ​

执行流程示意 ​

完整示例 ​

触发分支 ​

支持模式 ​

分支匹配示例 ​

触发事件 ​

常用事件 ​

触发事件示例 ​

Pipeline ​

配置项概览 ​

配置项详细说明 ​

name ​

runner ​

docker ​

docker.image ​

docker.build ​

docker.devcontainer ​

docker.volumes ​

git ​

services ​

service:docker ​

service:vscode ​

env ​

imports ​

label ​

stages ​

failStages ​

endStages ​

ifNewBranch ​

ifModify ​

breakIfModify ​

retry ​

allowFailure ​

lock ​

sandbox ​

Stage ​

配置项概览 ​

结构说明 ​

单个 Job ​

串行 Job ​

并行 Job ​

配置项说明 ​

name ​

ifNewBranch ​

ifModify ​

if ​

env ​

imports ​

retry ​

lock ​

Stage.image ​

jobs ​

Job ​

配置文件

基本结构

执行流程示意

完整示例

触发分支

支持模式

分支匹配示例

触发事件

常用事件

触发事件示例

Pipeline

配置项概览

配置项详细说明

name

runner

docker

docker.image

docker.build

docker.devcontainer

docker.volumes

git

services

service:docker

service:vscode

env

imports

label

stages

failStages

endStages

ifNewBranch

ifModify

breakIfModify

retry

allowFailure

lock

sandbox

Stage

配置项概览

结构说明

单个 Job

串行 Job

并行 Job

配置项说明

name

ifNewBranch

ifModify

if

env

imports

retry

lock

Stage.image

jobs

Job