配置文件

• 什么是 CI 配置文件？
• 配置文件存放位置
• 配置文件的基本语法结构
• 语法检查和自动补全
  • VSCode
  • Jetbrains
• 简化配置文件写法
• 文件引用

什么是 CI 配置文件？

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

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

Yaml 是一个可以转化为 JSON 的格式， 它比 JSON 更加易读，使用缩进区分数据结构， 并且拥有一些高级特性。

这是一个简单的、可工作的 云原生构建 配置文件：

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

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

1. 声明了在 main 分支在收到 push 事件时（即有新的 Commit 推送到 main 分支）
2. 会选择 Docker 镜像 node:22 作为执行环境
3. 依次执行任务 npm install 和 npm test

配置文件存放位置

云原生构建 约定的配置文件命名为 .cnb.yml，存放于仓库根目录下，配置文件即代码。

这意味着，配置文件可以通过 PR 进行变更，开源协作场景下，这十分重要。

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

配置文件的基本语法结构

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

# 流水线结构：数组形式
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 容器）中执行。

详细语法说明可参考： 语法说明

语法检查和自动补全

VSCode

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

本地开发配置方法，以 VSCode 为例：

先安装 redhat.vscode-yaml 插件，然后在 settings.json 中加入以下配置：

Jetbrains

1. 「Settings」「Languages & Frameworks」「Schemas and DTDs」「JSON Schema Mappings」

2. 点击新增按钮，设置 「Name」（名称随意填写）

3. 设置「Schema file or URL」

4. 「Add mapping for a file」

简化配置文件写法

配置文件是 Yaml 格式，可以利用更多 Yaml 特性（如锚点 & 、别名 * 和对象合并 << 符号）来简化配置文件。

一个简单的运用锚点和别名简化的例子如下：

# pull_request 和 push 事件的流水线完全一致，这种方式可以减少重复
.pipeline: &pipeline
  docker:
    image: node:22
  stages:
    - name: install
      script: npm install
    - name: test
      script: npm test

main:
  pull_request:
    - <<: *pipeline
  push:
    - <<: *pipeline

支持多级嵌套：

.jobs: &jobs
  - name: install
    script: npm install
  - name: test
    script: npm test

.pipeline: &pipeline
  docker:
    image: node:22
  stages: *jobs

main:
  pull_request:
    - <<: *pipeline
  push:
    - <<: *pipeline

提示

以上是 Yaml 自带特性，不能跨文件使用。

为了方便复用流水线配置，云原生构建 实现了更高级的特性：

include：可以跨文件引用流水线模板。

reference: 可以跨文件按属性路径引用变量。

文件引用

云原生构建 支持引用其他文件中的配置，以便于配置文件的拆分和复用以及流水线配置和敏感信息的分离。

详情参考文件引用