LV005-快速开始

一、配置文件

配置文件 | CNB 文档

1. 简介

云原生构建配置文件(.cnb.yml)描述了当仓库发生一些事件时（有新的 Commit 被推送、有新的 PR 请求等）， 云原生构建是否应该启动构建任务，如果启动构建的话，构建任务的每一步分别做什么。

云原生构建 的配置文件格式是 YAML，这一点与业界主流 CI 服务相同：

main: # 触发分支
  push: # 触发事件
    - docker:
        image: node:22 # 流水线执行环境，可以指定任意docker镜像
      stages:
        - name: install
          script: node -v

这个案例描述的流程如下：

（1）声明了在 main 分支在收到 push 事件时（即有新的 Commit 推送到 main 分支）

（2）会选择 Docker 镜像 node:22 作为执行环境

（3）依次执行任务 node -v 。

最终效果如下：

2. 存放位置

云原生构建约定的配置文件命名为 .cnb.yml，存放于仓库根目录下，配置文件即代码。这意味着，配置文件可以通过 PR 进行变更，开源协作场景下，这十分重要。

构建流程纳入版本管理，与源代码保持相同的透明度和变更流程，修改历史很容易追溯。

3. 基本语法结构

更详细的语法看这里：流水线语法 | CNB 文档

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

# 流水线结构：数组形式
main:
  push:
    # main 分支 - push 事件包含两条流水线：push-pipeline1 和 push-pipeline2
    - name: push-pipeline1 # 流水线名称，可省略
      stages:
        - name: job1
          script: echo 1
    - name: push-pipeline2 # 流水线名称，可省略
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # main 分支 - pull_request 事件包含两条流水线：pr-pipeline1 和 pr-pipeline2
    - name: pr-pipeline1 # 流水线名称，可省略
      stages:
        - name: job1
          script: echo 1
    - name: pr-pipeline2 # 流水线名称，可省略
      stages:
        - name: job2
          script: echo 2

等价与以下写法：

# 流水线结构：对象形式
main:
  push:
    # main 分支 - push 事件包含两条流水线：push-pipeline1 和 push-pipeline2
    push-pipeline1: # 流水线名称，必须唯一
      stages:
        - name: job1
          script: echo 1
    push-pipeline2: # 流水线名称，必须唯一
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # main 分支 - pull_request 事件包含两条流水线：pr-pipeline1 和 pr-pipeline2
    pr-pipeline1: # 流水线名称，必须唯一
      stages:
        - name: job1
          script: echo 1
    pr-pipeline2: # 流水线名称，必须唯一
      stages:
        - name: job2
          script: echo 3

其中 main 表示分支名称， push 和 pull_request 表示触发事件。一个事件包含多个 pipeline，支持数组和对象两种形式，并发执行。一个 pipeline 包含一组顺序执行的任务，在同一个构建环境（物理机、虚拟机或 Docker 容器）中执行。

二、触发规则

1. 基本规则

云原生构建会在收到事件时，从对应的分支获取、解析 .cnb.yml 配置文件，从中获取对应分支下对应事件的流水线配置，然后分配 Runner 执行构建。

以 main 分支代码 push 事件为例：

代码示例：

# .cnb.yml
main: # 触发分支
  push: # 触发事件，对应一个构建，可以包含多条 Pipeline。即可以是数组，也可以是对象。
    - stages: # 流水线1
        - echo "do some job"
    - stages: # 流水线1
        - echo "do some job"

更加详细的说明直接看文档吧：构建触发规则 | CNB 文档

2. 包含特定关键词

有时候我们只想提交，不想触发构建，是不是可以像GithubActions一样，当提交包含特定关键词时才触发流程呢？比如产生如下提交：

git commit -m "触发构建 [build]" # 触发构建
git commit -m "跳过构建"         # 跳过构建

当提交记录包含 [build] 的时候才构建，在cnb中，我们好像只能在 stage 或者job中使用if语句，所以我们可以这样编写 .cnb.yml：

main: # 触发分支
  push: # 触发事件
    - docker:
        image: node:22 # 流水线执行环境，可以指定任意docker镜像
      stages:
        - name: 显示node版本号(包含 [build] 才执行)
          if: |
            case "$CNB_COMMIT_MESSAGE" in *"[build]"* ) true ;; * ) false ;; esac
          script: node -v

        - name: 构建步骤1
          script: echo "构建步骤1..."
        
        - name: 构建步骤2(包含 [build] 才执行)
          if: |
            case "$CNB_COMMIT_MESSAGE" in *"[build]"* ) true ;; * ) false ;; esac
          script: echo "构建步骤2..."
        
        - name: 构建步骤3
          script: echo "构建步骤2..."

在 .cnb.yml 文件中， =~ 用于检查 $CNB_COMMIT_MESSAGE 是否包含 [build] 子串，从而决定是否执行某些构建步骤。一开始其实写的是[[ "$CNB_COMMIT_MESSAGE" =~ "[build]" ]]，但是好像报了[satisfy script] sh: 1: [[: not found，表明当前 Shell 环境不支持 [[ 语法，因为 [[ 是 Bash 的扩展语法，而脚本可能是在 sh （或其他不支持 [[ 的 Shell）中运行的。解决方案如下：

• 切换到 Bash：确保脚本在 Bash 环境中运行，因为 [[ 是 Bash 的特性。

• 使用兼容语法：如果无法切换到 Bash，可以使用 sh 兼容的语法，例如 case 或 expr 。

修改语法或，我们提交，这一次提交信息为：

git commit -m "特定提交触发对应步骤 [build]"

我们修改一下文件，然后再次提交：

git commit -m "更新README.md"

就会发发现这两个步骤被跳过了。