配置文件

# 什么是 CI 配置文件?

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

云原生构建 的配置文件格式是 Yaml,这一点与业界主流 CI 服务相同。 Yaml 是一个可以 转化为 JSON (opens new window) 的格式, 它比 JSON 更加易读,使用缩进区分数据结构, 并且拥有一些高级特性。更多 Yaml 介绍 (opens new window)

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

master:
  push:
    - docker:
        image: node:14
      stages:
        - name: 依赖安装
          script: npm install
        - name: 测试用例检查
          script: npm test

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

  1. 声明了在 master 分支在收到 push 事件时(即有新的 Commit 推送到 master 分支)的时候
  2. 会选择以 node:14 Docker 镜像 (opens new window) 启动的容器作为构建环境
  3. 依次执行任务 npm installnpm test

注意

push 事件里,以下两种情况会跳过流水线

  1. 最近一个 commit message 里带 [ci skip][skip ci]
  2. git push -o ci.skip

如:

git commit -m "feat: some feature [ci skip]"
git push origin master

git commit -m "feat: some feature"
git push origin master -o ci.skip

master 下 push 构建会跳过流水线执行

# 配置文件存放位置

云原生构建 遵循 Pipeline as Code 原则,即 CI 配置文件也应该如同项目源代码一样,存放在项目仓库中。这意味着配置文件也是纳入 Git 版本管理的,可以被其他人提 MR 修改,修改历史也很容易追溯。在开源共建场景,这十分重要,因为协同开发者不仅要看到你的源代码,还需要知道你的构建流程。

通常,约定配置文件命名为 .coding-ci.yml ,并且将其存放在项目的根目录下

注意:这里可以是个相对根目录的相对路径,也可以是一个远程仓库文件地址。

# 配置文件的基本语法结构

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

# 流水线结构:数组形式
master:
  push:
    - push-pipeline1
    - push-pipeline2
  merge_request:
    - mr-pipeline1
    - mr-pipeline2
# 流水线结构:对象形式
master:
  push:
    push-pipeline1: # 流水线名
      stages:
        - name: job1
          script: echo 1
    push-pipeline2: # 流水线名
      stages:
        - name: job2
          script: echo 2

  merge_request:
    mr-pipeline1: # 流水线名
      stages:
        - name: job3
          script: echo 1
    mr-pipeline2: # 流水线名
      stages:
        - name: job4
          script: echo 2

其中 master 表示分支名称, pushmerge_request 表示触发事件, 每个事件下面都可以有多个 pipeline (多个 pipeline 支持数组和对象两种形式), 一个 pipeline 是指一组顺序执行的任务,一个 pipeline 在同一个构建环境(物理机、虚拟机或 Docker 容器)中执行。

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

# 语法检查和自动补全

推荐使用语法检查和自动补全,提升书写配置文件时的流畅感。效果如下:

yaml-auto

配置方法,以 VS Code(Visual Studio Code) 为例:

1、安装 Yaml 插件 (opens new window)

2、配置 json-schema (opens new window)

在 VS Code 的 setting.json (opens new window) 中加入如下配置:

# 内置任务

支持内置任务及其参数的语法检查与自动补全。

schema options

具体做法是将内置任务参数说明从文档收归到代码注释中。 利用 typescript-json-schema (opens new window) 解析出 json schema , 在 vuepress 中用自定义组件从 json-schema 读取内置任务参数信息,渲染出 title任务名参数说明表 等信息。 保证 云原生构建 代码、文档、代码提示的一致性。

# 简化配置文件写法

配置文件是 Yaml 格式,可以利用更多 Yaml 特性(如锚点 & 、别名 * 和对象合并 << 符号)来简化配置文件。 更多 Yaml 高级特性 (opens new window)

一个最简单的运用锚点和别名简化的例子如下,如果 master 和 dev 分支的流水线完全一致,那么可以使用这种方式来减少重复的内容:

.pipeline: &pipeline
  docker:
    image: node
  stages:
    - name: 依赖安装
      script: npm install
    - name: 测试用例检查
      script: npm test

master:
  push:
    - <<: *pipeline

dev:
  push:
    - <<: *pipeline

另外一个案例是:在 MR 的时候只进行构建测试,但是在 tag push 的时候,不仅要执行构建测试,还需要执行发布步骤。

.build-fragment: &build-fragment
  - name: build
    script: npm run build
  - name: test
    script: npm test

.deploy-fragment: &deploy-fragment
  - name: release
    type: zhiyun:pkg
    options:
      product: PRODUCT
      name: NAME
      dist: ./release
      overlying: true
  - name: deploy
    type: zhiyun:update
    options:
      product: PRODUCT
      name: NAME

master:
  merge_request:
    - stages:
        - *build-fragment

"**":
  tag_push:
    - stages:
        - *build-fragment
        - *deploy-fragment

同样支持多级嵌套:

.fragment1: &fragment1
  - name: build
    script: npm run build
  - name: echo 1
    script: echo 1

.fragment2: &fragment2
  - *fragment1
  - name: echo 2
    script: echo 2

master:
  merge_request:
    - stages:
        - *fragment2

TIP

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

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

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

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