流水线语法

文章内容

基本概念
流水线 Pipeline
阶段 Stage
任务 Job
配置复用

基本概念

触发分支：对应代码仓库的分支，用于指定流水线在哪个分支中进行构建。
触发事件：指定出现哪种事件时触发构建，支持触发多条流水线。
Pipeline：表示一个流水线，包含一个或者多个阶段 Stage，每个 Stage 依次执行。
Stage：表示一个构建阶段，可以由一个或者多个任务 Job 组成。
Job：最基本的任务执行单元。

master: # 触发分支
  push: # 触发事件，对应一个构建，可以包含多条 Pipeline。即可以是数组，也可以是对象。
    - name: pipeline-1 # Pipeline 结构体
      stages:
        - name: stage-1 # Stage 结构体
          jobs:
            - name: job-1 # Job 结构体
              script: echo

master: # 触发分支
  push: # 触发事件，对应一个构建，通过对象指定流水线
    pipeline-key:
      stages:
        - name: stage-1 # Stage 结构体
          jobs:
            - name: job-1 # Job 结构体
              script: echo

流水线 Pipeline

一个 Pipeline 的基本配置如下：

name: 流水线名字
runner:
  tags: devnet
docker:
  image: node
  build: dev/Dockerfile
  volumes:
    - /root/.npm:copy-on-write
git:
  enable: true
  lfs: true
  submodules: true
services:
  - docker
env:
  TEST_KEY: TEST_VALUE
imports:
  - https://xxx/envs
  - ./env.txt
stages:
  - stage1
  - stage2
  - stage3
failStages:
  - stage1whenFail
  - stage2whenFail
ifModify:
  - a.txt
  - src/**/*
retry: 3
allowFailure: false

name

string

指定流水线名，默认为 pipeline。当有多条并行流水线时，默认流水线名为 pipeline、pipeline-1、pipeline-2 依此类推，可定义 name 指定流水线名来区分不同流水线作用

runner

Object

指定与指定构建节点相关的参数。

runner.tags

Array | String

指定使用具备哪些标签的构建节点，缺省值为 coding:public

示例

master:
  push:
    - runner:
        tags: default
        # tags:
        #   - default
        #   - others
      stages:
        - name: echo
          script: echo "hello world"

runner.cpus

Integer

指定构建需使用的最大 cpu 核数（memory = cpu 核数 * 2 G），其中 cpu 和 memory 不超过构建节点实际大小

未配置时，则取所选tags机器配置的默认值。

示例

# cpus = 1，memory = 2G
master:
  push:
    - runner:
        cpus: 1
      stages:
        - name: echo
          script: echo "hello world"

runner.affinity

Integer

配置构建节点的轮转副本数。默认值为 3。

这里会使用Hashring方式，根据项目名，生成固定数量（affinity 值）的 key，然后匹配固定数量的构建节点，依次选择执行任务，缓存友好。

因为使用 Hashring 方式，不同 key 匹配的构建节点可能重复，极端情况下匹配到的所有构建节点是同一个，每次执行都会使用这个构建节点。

// affinity = 5
               / Runner1 \
               - Runner2 -
mygroup/myproj - Runner3 - 
               - Runner4 -
               \ Runner5 /

示例：

master:
  push:
    - runner:
        # 使用带 coding:public 标签的构建节点
        tags: coding:public
        # 使用同时带 default 和 cpu-32 标签的构建节点
        # tags:
        #   - coding:public
        #   - coding:high-peformance
      stages:
        - name: echo
          script: echo "hello world"

docker

Object

指定 Docker 构建环境相关的参数。具体说明见构建环境

image: 指定 docker 需要的镜像，在当前 Pipeline 下的所有任务都将在这个镜像环境中执行。
build: 指定一个 Dockerfile，构建一个临时镜像，做为 image 的值使用。
volumes: 声明数据卷。

docker.image

String

指定 docker 需要的镜像，在当前 Pipeline 下的所有任务都将在这个镜像环境中执行，支持引用环境变量。

示例：

master:
  push:
    - docker:
        # 取 docker 官方镜像仓库中的 node:14 镜像作为构建容器
        image: node:14
      stages:
        - name: echo
          script: echo "hello world"

docker.build

指定一个 Dockerfile，构建一个临时镜像，做为 image 的值使用，支持引用环境变量。

Object | String
- build.dockerfile: Dockerfile路径。
- build.target: 对应docker build中--target参数，docker build会执行到指定的stage时停止。
- build.versionBy: 指定根据哪些文件，进行镜像版本控制。当指向的文件内容发生变化时，我们会认为是一个新的版本，然后重新触发docker build 进行镜像构建。具体的计算逻辑见这个表达式：md5(dockerfile + versionBy + buildArgs)。
- build.buildArgs: 在 docker build 时插入额外的构建参数 (--build-arg $key=$value), value 值为 null 时只加入 key (–build-arg $key)。
- build.ignoreBuildArgsInVersion: 版本计算是否忽略 buildArgs。详见build.versionBy中版本控制说明。

如果指定build为字符串，则等同于指定了build.dockerfile。

通过 Dockerfile 指定构建环境：

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

master:
  push:
    - docker:
        build:
          dockerfile: ./image/Dockerfile
          target: builder #对应docker build中--target参数
      stages:
        - stage1
        - stage2
        - stage3

Dockerfile versionBy 用法：

示例：将 pnpm 缓存到环境镜像中，加速后续`pnpm i`过程

master:
  push:
    # 通过 Dockerfile 指定构建环境
    - docker:
        build:
          dockerfile: ./Dockerfile
          versionBy:
            - package-lock.json
      stages:
        - name: pnpm i
          script: pnpm i

FROM node:16

RUN npm i -g pnpm  &&\
    pnpm config set store-dir /lib/pnpm

WORKDIR /tmp

COPY package.json package-lock.json ./

RUN pnpm i

docker.volumes

Array<String> | String

声明数据卷，多个数据卷可通过数组或者用,号做分割符传入

用途：

将文件存储在构建节点上，可在后续构建中复用。（type不为data时）
- 原理：将构建节点上目录 mount 到各容器中，该目录在流水线退出后会保留。可作为缓存用于后续流水线。该目录在构建节点上会按不同的 Git 仓库相互隔离。
将容器中的指定目录，共享给其他容器中使用。（仅type为data时）
- 原理：通过创建数据卷，然后 mount 到各容器中。与直接将构建节点上目录 mount 到容器中方式不同的是：当指定的目录在容器中已经存在，会先把容器中内容自动复制到数据卷，而不是将数据卷内容直接覆盖容器中目录。

支持引用环境变量，支持的格式：

<group>:<path>:<type>
<path>:<type>
<path>

各项含义：

group: 可选，数据卷分组，不同组间相互隔离
path: 必填，数据卷挂载绝对路径，支持绝对路径（/ 开头）或相对路径（./ 开头），相对于工作区
type: 可选，数据卷类型，缺省值为 copy-on-write，支持以下类型
- read-write 或 rw : 读写，并发写冲突由使用方处理，适用于数据持久化场景
- read-only 或 ro : 只读，写操作抛出异常
- copy-on-write 或 cow : 读写，变更（新增、修改、删除）在构建成功后合并，适用于一致性缓存场景
- copy-on-write-read-only : 只读，变更（新增、删除、修改）在构建结束后丢弃
- data : 创建一个临时数据卷，该数据卷在流水线结束时会自动清理

volumes 示例：

示例 1 : 挂载构建节点上目录到容器中，实现本地缓存效果

master:
  push:
    - docker:
        image: node:14
        # 声明数据卷
        volumes:
          - /data/config:read-only
          - /data/mydata:read-write

          # 使用缓存，同时更新
          - /root/.npm

          # 使用 master 缓存，同时更新
          - master:/root/.gradle:copy-on-write

      stages:
        - stage1
        - stage2
        - stage3
  merge_request:
    - docker:
        image: node:14

        # 声明数据卷
        volumes:
          - /data/config:read-only
          - /data/mydata:read-write

          # 使用 copy-on-write 缓存
          - /root/.npm
          - node_modules

          # mr 使用 master 缓存，但不更新
          - master:/root/.gradle:copy-on-write-read-only

      stages:
        - stage1
        - stage2
        - stage3

示例 2：将打包在容器中文件，共享到其他容器中使用

# .coding-ci.yml
master:
  push:
    - docker:
        image: go-app-cli # 假设有个go应用在镜像的/go-app/cli路径下
        # 声明数据卷
        volumes:
          # 此路径在go-app-cli镜像存在，所以执行环境镜像时，会将此路径内容复制到临时数据卷中，可共享给其他任务容器里使用
          - /go-app
      stages:
        - name: show /go-app-cli in job container
          image: alpine
          script: ls /go-app

git

Object

提供 Git 仓库相关配置。

git.enable

Boolean

默认值为 true。指定是否拉取代码。

mergeable、 branch.delete 事件，默认值为 false。

git.lfs

Boolean

默认值为 true。指定是否拉取 Git LFS(Git Large File System)。

git.submodules

Boolean | Object
- enable 是否指定是否要拉取子项目（submodules）。默认值为 true。
- remote 执行git submodule update时是否添加--remote参数，用于每次拉取submodule最新的代码

如果指定submodules为布尔值，则等同于指定了submodules.enable。

services

Array<String>

用于声明构建时需要的服务，格式：name:[version], version 是可选的。

目前支持的服务有：

docker
vscode

docker

开启dind服务，当构建过程中需要使用 docker build，docker login 等操作时声明。

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

vscode

vscode，需要启动远程开发服务时声明。用法参见vscode:go

env

Object

指定环境变量。可以定义一组环境变量，在任务执行中使用。对当前 Pipeline 内的所有任务均有效。

imports

String | Array<String>

指定某个本仓库或另外 Coding Git 仓库文件路径，可以读取此文件作为环境变量来源。
一般使用一个私有仓库来存放诸如 npm 或者 docker 等账号密码。

同名时优先级：

当配置 imports 为数组时，如遇到参数重复的情况，后面的配置会覆盖前面的。
如果和 env 参数中重复，那么 env 中的参数会覆盖掉 imports 文件中的。

访问控制：

访问者权限，与文件中是否含有 allow_slugs 保留字段有关：
- 如果不含有 allow_slugs 字段，会检查流程发起人是否具备该仓库的权限。
- 如果含有 allow_slugs，那么只会检查当前项目是否在 allow_slugs 指定的白名单中，而不会检查流程发起人是否有权限。
  allow_slugs 为字符串数组，表示允许特定的项目使用。形如 team/project/repo，
  其中，可以使用 glob 模式来匹配，可以满足匹配一个组下面的所有项目，如 coding-ci/**/**。
  *警告：请谨慎使用全匹配如 **，这会导致所有仓库都可以使用该文件！\*

支持的文件格式列表：

yaml：所有根路径下的属性名都会导出为环境变量，解析文件后缀为 yml。
json: 所有根路径下的属性名都会导出为环境变量，解析文件后缀为 json。
plain: 每行格式为 key=value，除了以上涉及的后缀都以此方式解析。（不推荐）

变量赋值：

imports 文件路径可读取环境变量。若是数组，下面的文件路径可读取上面文件中的变量

master:
  push:
    - imports:
        - ./env1.json
        - $FILE
        - https://xxx/xxs.yml
      stages:
        - name: echo
          script: echo $TEST_ENV

stages

Array<Job>

定义一组阶段任务，每个阶段串行运行。

failStages

Array<Job>

定义一组失败阶段任务。当正常流程失败，会依次执行此阶段任务。

ifNewBranch

Boolean

默认值为 false，当前分支属于新分支（即 CODING_IS_NEW_BRANCH 为 true）时，才执行此 Pipeline。

注：当同时存在 ifNewBranch / ifModify 时，其中有一个条件满足，此 Pipeline 就会执行。

ifModify

String | Array<String>

指定一个 glob 文件匹配规则或者文件名列表，只有命中规则时，才执行此 Pipeline。

案例一：

当修改文件列表中包含 a.js 或者 b.js，会执行此 Pipeline。

ifModify:
  - a.js
  - b.js

案例二：

当修改文件列表中包含有 js 后缀的文件时，会执行此 Pipeline。
其中 **/*.js 表示匹配所有子目录中的 js 后缀文件，*.js 表示所有根目录中的 js 后缀文件。

ifModify:
  - **/*.js
  - *.js

案例三：

反向匹配，除目录 legacy 以外有变更时触发

ifModify:
  - "**"
  - "!(legacy)/**"

breakIfModify

Boolean

job 执行前，如果源分支已更新，则终止构建。

retry

Number

失败重试次数，默认为 0，表示不重试。

allowFailure

Boolean

允许当前流水线失败，默认为 false。

当此参数设置为 true 时，流水线的失败的状态不会上报到 Coding 上。

阶段 Stage

jobs

Array<Job> | Object<name,Job>

如果一个`Stage` 只有一个 `Job`，那么可以省掉 `Stage` 直接书写这个 `Job`

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

可以简化为以下写法:

stages:
  - name: job A
    script: echo hello

当值为数组（有序）时，那么这组 `Job` 会依次串行执行

# 串行
stages:
  - name: install
    jobs:
      - name: job1
        script: echo "job1"
      - name: job2
        script: echo "job2"

当值为对象（无序）时，那么这组 `Job` 会并行执行

# 并行
stages:
  - name: install
    jobs:
      job1:
        script: echo "job1"
      job2:
        script: echo "job2"

多个 `Job` 可以选择串行执行，也可以并行执行

先串行后并行的写法如下：

master:
  push:
    - stages:
        - name: serial first
          script: echo "serial"
        - name: parallel
          jobs:
            parallel job 1:
              script: echo "1"
            parallel job 2:
              script: echo "2"
        - name: serial next
          script: echo "serial next"

name

String

指定 Stage 名称。

ifNewBranch

Boolean

默认值为 false，只有当前分支属于新分支（即 CODING_IS_NEW_BRANCH 为 true）时，才执行此 Stage。

注：当同时存在 ifNewBranch / ifModify / if 时，其中有一个条件满足，此 Stage 就会执行

ifModify

String | Array<String>

指定只有当次有相应文件变动时，才执行此 Stage。
是一个 glob 匹配字符串，或者是一个 glob 匹配字符串数组。

if

String | Array<String>

一个或者多个 Shell 脚本，根据脚本执行的退出程序码（exit code）来判断是否执行此 Stage。
当退出程序码为 0 时，表示需要执行本步骤。

判断某个变量的值

shell 表达式语法

master:
  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

判断任务执行的输出

master:
  push:
    - stages:
        - name: make info
          script: echo 'haha'
          exports:
            info: RESULT
        - name: run if RESULT is haha
          if: |
            [ "$RESULT" = "haha" ]
          script: echo $RESULT

env

同 Pipeline env，只对当前 Stage 生效。

Stage.env 优先级比 Pipeline.env 高。

imports

同 Pipeline imports，只对当前 Stage 生效。

retry

number

失败重试次数，默认为 0，表示不重试。

lock

Boolean ｜Object

给 stage 设置锁，stage 执行完后自动释放锁，锁不能跨仓库使用。

表现：任务 A 获取到锁后，任务 B 再申请锁，将等待锁释放后，才能获取到锁继续执行任务。

lock.key

Boolean

自定义锁名,默认值为 分支名-流水线名-stage下标

lock.expires

Number

锁过期时间，过期后自动释放锁。单位“秒”。默认值为 3600 秒，即一小时。

lock.wait

Boolean

锁被占用是否等待。默认值false

lock.timeout

Number

指定等待锁的超时时间。单位“秒”。默认值为 3600 秒，即一小时。

# 例1: lock 是 Boolean 格式
master:
  push:
   - stages:
      - name: stage1
        lock: true
        jobs:
          - name: job1
            script: echo "job1"


# 例2: lock 是 Object 格式
master:
  push:
   - stages:
      - name: stage1
        lock:
          key: key
          expires: 600  # 10分钟
          wait: true
          timeout: 60   # 最多等待 1分钟
        jobs:
          - name: job1
            script: echo "job1"

image

String

指定当前Stage需要的镜像，在当前 Stage 下的所有任务默认都将在这个镜像环境中执行。

任务 Job

Job 是最基本的任务执行单元。可以分为三类：

脚本任务

- name: install
  script: npm install

如果希望 script 拥有自己的执行环境，而不是在 pipeline 所在环境执行，可以通过增加 image 属性指定执行环境。

- name: install
  image: node:14
  script: npm install

内置任务

为流水线内置支持的一些任务。详细说明：内置任务

示例：

name: install
type: docker:cache
options:
  key1: value1
  key2: value2

插件任务

使用Docker镜像作为流水线任务。

示例：

- name: npm publish
  image: plugins/npm
  imports: https://xxx/npm-secret.yml
  settings:
    username: $NPM_USER
    password: $NPM_PASS
    email: $NPM_EMAIL
    folder: ./

name

String

指定 Job 名称。

ifModify

同 Stage ifModify。不同点在于只对当前 Job 生效。

ifNewBranch

同 Stage ifNewBranch。不同点在于只对当前 Job 生效。

if

同 Stage if。不同点在于只对当前 Job 生效。

breakIfModify

同 Pipeline breakIfModify。不同点在于只对当前 Job 生效。

skipIfModify

job 执行前，如果源分支已更新，则跳过当前 job。

env

同 Stage env，只对当前 Job 生效。

Job env 优先级比 Pipeline env、Stage env 高。

imports

同 Stage imports，只对当前 Job 生效。

exports

Object

设置环境变量，生命周期为当前 Pipeline，详情请见 #修改环境变量

注：每个任务执行结束后，都有一个 result 对象，result 可通过 exports 导出到环境变量。

比如，把系统的日期导出到环境变量中，可以这么写：

name: export env
script: date
exports:
  info: CURR_DATE

缺省情况下 result 有哪些变量？

缺省情况下，一个任务执行完，会有以下变量可以引用。

{
  code, // 任务退出码
  info, // 按时间顺序混合了标准输出和错误输出流的内容
  stdout, // 标准输出流内容
  stderr  // 错误输出流内容
}

如何向 result 对象中增加自定义变量？

比如：通过自定义变量来传递信息到环境变量，进而影响构建的目标。

name: add vars into result
script: node myJob.js
exports:
  report_url: ENV_REPORT_URL

可以通过 set-output 指令来输出自定义变量到 result 对象中。

如果你使用的编程语言为 Node.js，对应的示例代码如下：

console.log(`##[set-output key=${escape(value)}]`);

通过 shell 调起 node 命令编码，对应的示例代码如下：

export rawString="value"
encodeString=$(node -pe "escape(process.env.rawString)")
echo "##[set-output key=$encodeString]"

工作原理

通过如下约定的格式，CI 会从标准输流里识别变量，自动放入 result 对象中。

##[set-output key=value]

这并不是 Coding CI 的首创，这一约定来自 Github Actions。

因此，当你开发的插件运行在 Github Actions 上时，有相同的效果。

内置任务的 result

内置任务通过 return result 精确返回任务结果。在文档上可以看到每个内置任务对自己输出的描述。

timeout

Number

设置单个任务的超时时间（单位毫秒），如果不传，默认为 1 小时，最大不能超过 12 小时。

超时策略

默认整个 job 执行时长超过1个小时，会触发超时逻辑。如果有声明timeout参数，则超时时间改为timeout，但最大不能超过 12 个小时。
默认每个 job 如果连续10分钟内，输出流没有任何内容，会触发超时。如果有声明timeout参数，则改为持续timeout时间内，但最大不能超过整个 job 的执行时长。

allowFailure

Boolean | String

允许本步骤失败，默认为 false。

当此参数设置为 true 时，本步骤如果失败，也不会影响接下来流程的执行，并且不会影响最后的结果。

可以读取环境变量

lock

Boolean ｜Object

给 job 设置锁，job 执行完后自动释放锁，锁不能跨仓库使用。

表现：任务 A 获取到锁后，任务 B 再申请锁，将等待锁释放后，才能获取到锁继续执行任务。

lock.key

Boolean

自定义锁名,默认值为 分支名-流水线名-stage下标-job名

lock.expires

Number

锁过期时间，过期后自动释放锁。单位“秒”。默认值为 3600 秒，即一小时。

lock.wait

Boolean

锁被占用是否等待。默认值false

lock.timeout

Number

指定等待锁的超时时间。单位“秒”。默认值为 3600 秒，即一小时。

# 例1: lock 是 Boolean 格式
name: 锁
lock: true
script: echo 'job 锁'

# 例2: lock 是 Object 格式
name: 锁
lock:
 key: key  
 expires: 10 
 wait: true
script: echo 'job 锁'

retry

Number

失败重试次数，默认为 0，表示不重试。

script

String | Array<String>

指定任务要执行的脚本，指定为数组时，会自动使用 && 拼接多行脚本。执行脚本的进程退出码，会作为这个 job 的退出码。

commands

String | Array<String>

作用同script参数, 优先级比 script 高。主要为了兼容 Drone CI 语法

type

String

指定该步骤所要执行的内置任务。

options

Object

指定内置任务的相应参数。

optionsFrom

String

指定内置任务的相应参数。

使用Git仓库文件的方式指定内置任务的相应参数。

options 和 optionsFrom 可以一起使用，也可以单独使用。如果一起使用的话 options 中字段优先级高于 optionsFrom ，即相同字段，options 会覆写 optionsFrom 中的任务。

image

String

指定当前 job 执行的image, 用于 docker image as env 或 docker image as plugins

settings

Object

指定该镜像任务执行所需的参数。

settingsFrom

String | Array<String>

使用 Git仓库文件的方式指定镜像任务的相应参数。

支持的文件格式

yaml：所有根路径下的属性名都会导出为环境变量，解析文件后缀为 yml。
json: 所有根路径下的属性名都会导出为环境变量，解析文件后缀为 json。

settings 和 settingsFrom 可以一起使用，也可以单独使用。如果一起使用的话 settings 中字段优先级高于 settingsFrom，即相同字段，settings 会覆写 settingsFrom 中的任务。

权限控制

默认情况下，只有流水线触发者有settingsFrom指定路径的可读权限时，才允许读取文件。

可以通过在配置文件中加入allow_images字段, 授权给其他仓库或镜像读取：

示例：

同时限制 images 和 slugs ，可以通过 glob 模式匹配。

allow_images: 
  slugs:
    - a/b
  images: 
    - a/b

仅限制 images，不限制 slug：

allow_images: 
  images: 
    - a/b

可进一步简写为：

allow_images: 
  - a/b

settingsFrom 可以写在 Dockerfile 中，比如：

FROM node:14
LABEL coding-ci.settings-from="https://xxx.com/xxx/xxx/blob/master/settings.json"

args

Array<String>

指定执行镜像时传递的参数，内容将会追加到 ENTRYPOINT 中，仅支持数组。

示例：

- name: npm publish
  image: plugins/npm
  args: 
    - ls

将执行 docker run plugins/npm ls

任务退出码

0: Number，任务成功, 继续执行。
78: Number，任务成功，但中断当前 Pipeline 的执行。可在自定义脚本中主动执行exit 78，达到中断流水线效果。
other: Number，任务失败，同时中断当前 Pipeline 的执行。

配置复用

include

用于引用本地仓库、其他仓库以的配置文件。利用此特性，可以将 配置文件 拆分。实现流水线模板等功能。

# .coding-ci.yml

include:
  - '.ci/template.yml'

合并策略

多份配置文件，将采用对象 merge 的模式合并配置。merge 合并策略：

map : 同名 key 覆盖
array : 子元素追加

注意：

本地的 .coding-ci.yml 会覆盖 include 中的配置，include 数组中后面的配置会覆盖前面的配置。
支持嵌套 include，include 的本地文件路径相对于项目根目录。
最多支持 include 50 个配置文件。
不支持引用 submodule 中的文件。
不支持跨文件使用 yaml锚点功能。

示例 1

# template.yaml
master:
  push:
    pipeline_2:
      env:
        ENV_KEY1: xxx
        ENV_KEY3: inner
      services:
        - docker
      stages:
        - name: echo
          script: echo 222

# .coding-ci.yml
include:
  - https://xxx/template.yml

master:
  push:
    pipeline_1:
      stages: 
        - name: echo
          script: echo 111
    pipeline_2:
      env:
        ENV_KEY2: xxx
        ENV_KEY3: outer
      stages:
        - name: echo
          script: echo 333

merge 后的配置

master:
  push:
    pipeline_1:            # key不存在，合并时新增
      stages: 
        - name: echo
          script: echo 111
    pipeline_2:
      env:
        ENV_KEY1: xxx        
        ENV_KEY2: xxx      # key不存在，合并时新增
        ENV_KEY3: outer    # 同名 key， 合并时覆盖
      services:
        - docker
      stages:              # 数组在合并时，追加
        - name: echo
          script: echo 222
        - name: echo
          script: echo 333

示例 2

分离环境变量为单独文件

# .coding-ci.yml
include: 
- https://xxx/.coding-ci.common.yml

# .coding-ci.env.yml
CODE_SCAN_PATH: ./src
CDN_PATH: ./dist/cdn

# https://xxx/.coding-ci.common.yml
master:
  push:
    - services:
        - docker
      label:
        type:
          - MASTER
        class:
          - MAIN
      imports:
        - .coding-ci.env.yml    # 通过 `imports` 的方式来注入环境变量
      stages:
        - name: 查看注入的环境变量
          script:
            - echo $CDN_PATH
            - echo $CODE_SCAN_PATH

!reference

使用自定义标签 !reference 可以实现变量复用。不同于YAML锚点，!reference 可以跨 include 文件使用。

变量复用示例

a.yml

.val1:
  echo1: echo hello
.val2:
  friends:
    - one:
      name: tom
      say: !reference [.val1, echo1]

.coding-ci.yml

include:
  - ./a.yml
.val3: 
  size: 100
master:
  push:
    - stages:
        - name: echo hello
          script: !reference [.val2, friends, '0', say]
        - name: echo size
          env:
            SIZE: !reference ['.val3', 'size']
          script: echo my size ${SIZE}

解析后的结果是:

master:
  push:
    - stages:
        - name: echo hello
          script: echo hello
        - name: echo size
          env:
            SIZE: 100
          script: echo my size ${SIZE}

vscode 配置

安装 vscode yaml 插件后，为了在 vscode 编写带自定义标签 !reference 的 yaml 文件时不报错，需要如下配置：

setting.json

"yaml.customTags": [
    "!reference sequence",
]

Tips:
为避免编写时 yaml 插件根据 oci schema 把第一层变量名当做分支名，有错误提示，!reference 所在的第一层变量名可用 . 开头，如：.val1。

问题反馈 >

2023-02-21最近更新

感谢反馈有用

感谢反馈没用

流水线语法

name

runner

runner.tags

runner.cpus

docker

docker.image

docker.build

示例：将 pnpm 缓存到环境镜像中，加速后续pnpm i过程

示例 1 : 挂载构建节点上目录到容器中，实现本地缓存效果

示例 2：将打包在容器中文件，共享到其他容器中使用

git

git.enable

git.lfs

git.submodules

services

docker

vscode

stages

failStages

breakIfModify

retry

allowFailure

jobs

如果一个Stage 只有一个 Job，那么可以省掉 Stage 直接书写这个 Job

当值为数组（有序）时，那么这组 Job 会依次串行执行

当值为对象（无序）时，那么这组 Job 会并行执行

多个 Job 可以选择串行执行，也可以并行执行

name

ifNewBranch

ifModify

if

env

imports

retry

lock

lock.key

lock.expires

lock.wait

lock.timeout

image

name

ifModify

ifNewBranch

if

breakIfModify

skipIfModify

env

imports

exports

timeout

allowFailure

lock

lock.key

lock.expires

lock.wait

lock.timeout

retry

script

commands

type

options

optionsFrom

image

settings

settingsFrom

权限控制

args

任务退出码

配置复用

include

合并策略

示例 1

示例 2

!reference

变量复用示例

vscode 配置

示例：将 pnpm 缓存到环境镜像中，加速后续`pnpm i`过程

如果一个`Stage` 只有一个 `Job`，那么可以省掉 `Stage` 直接书写这个 `Job`

当值为数组（有序）时，那么这组 `Job` 会依次串行执行

当值为对象（无序）时，那么这组 `Job` 会并行执行

多个 `Job` 可以选择串行执行，也可以并行执行