云原生构建 / 流水线 / 内置任务

内置任务

文章内容

功能简介
使用方式
内置任务列表

功能简介

在每一个 Job 操作中，除了使用自定义的 script、插件任务 外，我们还扩展了一些比较常用的内置任务。

内置任务 与 其他任务 的区别：

运行环境不同：内置任务运行在 Master 可信区域；其他运行在 Runner 用户空间，物理上是隔离的。
鉴权方式不同：内置任务使用平台级票据，平台之间鉴权，用户无需提供票据；其他任务则为用户级票据，一般由被调方颁发。
信任关系不同：内置任务涉及三方，信任关系为 B2B2C；其他任务只涉及两方（调方和被调方），信任关系为 B2C。
调用方式不同：内置任务只能声明式调用，其他任务则可以直接命令式调用。

使用方式

通过 Job 中 type 属性，指定内置任务类型。通过 options 或 optionsFrom 参数，指定内置任务的参数。

实例：

master:
  push:
    -   stages:
      -   name: trigger
        type: coding-ci:apply
        options:
          configFrom: ./test/.coding-ci.yml
          event: api_trigger_test

内置任务列表

目前支持的内置任务有：

coding-ci:apply

在当前 Git 仓库，触发指定事件流水线。

适用事件

push
branch.create
tag_push
api_trigger

参数

config

type: String
required: false

指定流水线配置内容。

configFrom

type: String
required: false

指定一个 本地文件 或 Coding Git 文件作为配置文件。

按以下顺序依次取值，取到为止：

config
configFrom
当前仓库 .coding-ci.yml

event

type: String
required: false
default: api_trigger

要执行的自定义事件名，必须为 api_trigger 或以 api_trigger_ 开头。

env

type: Object
required: false

指定触发目标仓库流水线时的环境变量。

默认值情况下，当前Job可见的环境内置任务，都会传递给新的流水线。

同时默认会有如下环境变量，用户无法覆盖：

API_TRIGGER_REPO_SLUG，含义同 CI 默认环境变量中的 CODING_REPO_SLUG
API_TRIGGER_REPO_ID，含义同 CI 默认环境变量中的 CODING_REPO_ID
API_TRIGGER_USER，含义同 CI 默认环境变量中的 CODING_BUILD_USER
API_TRIGGER_BRANCH，含义同 CI 默认环境变量中的 CODING_BRANCH
API_TRIGGER_COMMIT，含义同 CI 默认环境变量中的 CODING_COMMIT
API_TRIGGER_COMMIT_SHORT，含义同 CI 默认环境变量中的 CODING_COMMIT_SHORT

sync

type: Boolean
required: false
default: false

是否等待本次 apply 流水线执行成功，再执行下一个任务。

continueOnBuildError

type: Boolean
required: false
default: false

sync:true下，触发的流水线构建失败时，是否继续执行下个任务。

ignoreGitStatus

type: Boolean
required: false
default: false

是否忽略设置 git status。

忽略后流水线将不会出现在 commit checks 中。

输出结果

{
    "code": 0,
    "success": true, // 是否成功触发构建
    "message": "success",
    "data": {
        "sn": "coding-ci-60-1547175336738"
    },
    "buildSuccess": true, // 触发的构建是否成功，此key仅在同步模式下存在
    "lastJobExports": {}, // 触发的流水线最后一个job导出的环境变量
}

示例：

master:
  push:
    -   stages:
        -   name: trigger
          type: coding-ci:apply
          options:
            config: |
              master:
                api_trigger_test: 
                -   stages:
                  -   name: test
                    script: echo test

            event: api_trigger_test

master:
  push:
    -   stages:
        -   name: trigger
          type: coding-ci:apply
          options:
            configFrom: ./test/.coding-ci.yml
            event: api_trigger_test

master:
  push:
    -   stages:
        -   name: trigger
          type: coding-ci:apply
          options:
            # 执行当前配置文件的其它事件
            event: api_trigger_test
  api_trigger_test:
    -   stages:
        -   name: test
          script: echo test

coding-ci:trigger

在当前仓库中，触发另外一个仓库的自定义事件流水线。

适用事件

ALL

参数

token

type: String
required: true

访问令牌。用于判断是否有目标仓库的权限。

slug

type: String
required: true

目标仓库的完整路径，如：team/group/repo。

event

type: String
required: true

触发的自定义事件名，必须是 api_trigger 或以api_trigger_ 开头。

需要目标仓库配置了对应事件的流水线，才可以触发。

branch

type: String
required: false

触发分支。默认为默认分支。

targetRef

type: String
required: false

预合并分支。默认为空

env

type: Object
required: false

指定触发目标仓库流水线时的环境变量。

同时默认会有如下环境变量，用户无法覆盖：

API_TRIGGER_REPO_SLUG，含义同 CI 默认环境变量中的 CODING_REPO_SLUG
API_TRIGGER_REPO_ID，含义同 CI 默认环境变量中的 CODING_REPO_ID
API_TRIGGER_USER，含义同 CI 默认环境变量中的 CODING_BUILD_USER
API_TRIGGER_BRANCH，含义同 CI 默认环境变量中的 CODING_BRANCH
API_TRIGGER_COMMIT，含义同 CI 默认环境变量中的 CODING_COMMIT
API_TRIGGER_COMMIT_SHORT，含义同 CI 默认环境变量中的 CODING_COMMIT_SHORT

sync

type: Boolean
required: false
default: false

是否等待本次 apply 流水线执行成功，再执行下一个任务。

continueOnBuildError

type: Boolean
required: false
default: false

sync:true下，触发的流水线构建失败时，是否继续执行下个任务。

输出结果

{
    "code": 0,
    "success": true, // 是否成功触发构建
    "message": "success",
    "data": {
        "sn": "coding-ci-60-1547175336738"
    },
    "buildSuccess": true, // 触发的构建是否成功，此key仅在同步模式下存在
    "lastJobExports": {}, // 触发的流水线最后一个job导出的环境变量
}

配置示例

在当前仓库触发一个项目 master 分支的事件名为 api_trigger_test 的流水线。

该流水线配置文件使用项目 master 分支的 .coding-ci.yml 文件。

使用 $CODING_TOKEN 查询用户是否有项目权限。

master:
  push:
    -   stages:
      -   name: trigger
        type: coding-ci:trigger
        imports: https://xxx/envs
        options:
          token: $CODING_TOKEN
          slug: team/project/reop
          branch: master
          event: api_trigger_test

coding-ci:await & resolve

对应以下两个内置任务：

coding-ci:await
coding-ci:resolve

用于将多个 pipeline 相互配合，以达到跨 pipeline 、跨机器、跨集群（pipeline.runner）构建的效果。

await 会等待 resolve 的执行，执行 resolve 的 pipeline 可以向匹配的 await pipeline 传递变量或文件。

TIP
await-resolve 同 apply、trigger 的区别：
前者指一个 pipeline 触发新事件，开启新的构建。
后者指一个构建中某 pipeline 执行到 await 任务时等待对应 key 的 resolve 通知才会继续进行。

适用事件

ALL

await 参数

key

type: String
required: true

配对 Key

resolve 参数

key

type: String
required: true

配对 Key

dist

type: String
required: false

要传递的文件目录。

相对工作区，该目录下的文件都会被传递。

比如：dist: /xxx/ 可以把 /xxx/** 下的文件做为传递对象。

data

type: Object
required: false

指定要传递的变量

key:value 格式，支持多级。示例：

-   name: resolve a json
  type: coding-ci:resolve
  options:
    key: demo
    data:
      a: 1
      b:
        c: 2

await 任务的结果，是 resolve 声明的 data 对象。

可以通过 exports 访问这个对象，示例：

-   name: await a json
  type: coding-ci:await
  options:
    key: demo
  exports:
    a: VAR_A
    b.c: VAR_B
-   name: show var
  script:
    -   echo ${VAR_A}    # 1
    -   echo ${VAR_B}    # 2

当然，也可以不传送任务内容，仅仅表示一个等待动作：

-   name: ready
  type: coding-ci:resolve
  options:
    key: i-am-ready

-   name: ready
  type: coding-ci:await
  options:
    key: i-am-ready

输出结果

{
  // resolve 返回的 data 内容
  "data":{}
}

使用限制

一个 resolve 或 await 任务仅能关联一个 key
一个 key 仅能关联一个 resolve 任务，但可以关联 0 或多个 await 任务

死锁检测

await 和 resolve 相互配合可以完成灵活的流程控制，但也会引入更复杂的边界情况，比如：

pipeline-1 和 pipeline-2 相互 await，即：死锁
多条 pipeline 间存在 await 环，即：间接死锁
await 一个不存在的 key，或者 key 没有关联 resolve，即：无限等待
resolve 所在 pipeline 执行失败，对应的 await 陷入无限等待
多个 resolve 任务关联同一个 key，即抛出异常
死锁检测 机制会自动检测以上异常，结束 await 的等待状态，抛出 dead lock found. 异常。

await 和 resolve 的在配置文件中顺序不影响运行结果，即最后 await 任务一定是会等待相应的 resolve 完成，这种情况不会被死锁检测机制终止。

配置样例

传送文件

master:
  push:
    -   runner:
        tags: amd64
      stages:
        -   name: hello
          script: 
            -   echo hello 
            -   mkdir ./files/ 
            -   touch ./files/file1
            -   touch ./files/file2
        -   name: resolve files
          type: coding-ci:resolve
          options:
            key: you-nide-kuaidi
            dist: files
    -   runner:
        tags: arm
      stages:
        -   name: hello
          script: echo hello
        -   name: await the file
          type: coding-ci:await
          options:
            key: you-nide-kuaidi
        -   name: show files
          script: ls -l files

docker:cache

构建一个Docker镜像中，在未来的构建中重复使用。

可以避免网络资源如 依赖包 重复下载。

适用事件

ALL

参数

dockerfile

type: String
required: true

用于构建缓存镜像的 Dockerfile 路径。

by

type: Array | String
required: false

用来声明缓存构建过程中依赖的文件列表。

注意：未出现在 by 列表中的文件，除了 dockerfile，其他在构建缓存镜像过程中，都当不存在处理。

支持数组格式
支持字符串格式，多个文件用英文逗号分隔。

byFromFile

type: String
required: false

从指定本地文件中读取列表，一行一个文件名，作用同 by。byFromFile 比 by 优先级更高。

versionBy

type: Array
required: false

用来进行版本控制，未传入 versionBy，则默认取 by 或 byFromFile 的值进行版本控制。

versionBy 所指向的文件内容发生变化，我们就会认为是一个新的版本，具体的计算逻辑见这个表达式：md5(dockerfile + versionBy + buildArgs)

buildArgs

type: Object
required: false

在 docker build 时插入额外的构建参数 (--build-arg $key=$value), value 值为 null 时只加入 key (--build-arg $key)

target

type: String
required: false

对应 docker build 的--target参数, 用于将Dockerfile中某个镜像作为缓存。

sync

type: Boolean
required: false
default: true

同步模式，是否等待 docker push 成功后才继续。

ignoreBuildArgsInVersion

type: Boolean
required: false
default: false

版本计算是否忽略buildArgs。详见版本控制。

输出结果

{
  // 缓存对应的 docker image name
  "name":"docker-cache:xxx"
}

配置示例

master:
  push:
  -   docker:
      image: node:12
    stages:
    -   name: build cache image
      type: docker:cache
      options:
        dockerfile: cache.dockerfile
        # by 支持以下两种形式：数组、字符串
        by:
          -   package.json
          -   package-lock.json
        # by: package.json,package-lock.json
        versionBy:
          -   package-lock.json
      exports:
        name: DOCKER_CACHE_IMAGE_NAME
    -   name: use cache
      image: $DOCKER_CACHE_IMAGE_NAME
      commands:
        -   cp -r "$NODE_PATH" ./node_modules
    -   name: build with cache
      script:
        -   npm run build

其中，cache.dockerfile 是一个用于构建缓存的 Dockerfile 。示例：

# 选择一个 Base 镜像
FROM node:12

# 设置工作目录
WORKDIR /space

# 将 by 中的文件列表 COPY 过来
COPY . .

# 根据 COPY 过来的文件进行依赖的安装
RUN npm ci

# 设置好需要的环境变量
ENV NODE_PATH=/space/node_modules

vscode:go

启动远程开发服务

适用事件

branch.create
api_trigger

参数

keepAliveTimeout

type: Number
required: false
default: 300000

工作区 keepAlive 超时，单位毫秒。最大值不得超过 12 个小时。

输出结果

{
    // 远程开发地址，如需在vscode:go任务前获取远程开发地址，可直接使用`VSCODE_WEB_URL`环境变量
    "url":""
}

配置示例

使用 Dockerfile 自定义开发环境，并安装 code-server。

code-server 官方文档：

#.tide/Dockerfile
FROM node:14

# install code-server and vscode extension
RUN curl -fsSL https://code-server.dev/install.sh | sh &&\
    code-server --install-extension redhat.vscode-yaml &&\
    code-server --install-extension orta.vscode-jest &&\
    code-server --install-extension dbaeumer.vscode-eslint &&\
    code-server --install-extension eamodio.gitlens &&\
    echo done

# 安装 zsh 并替换 sh（非必需，如有问题可去掉）
RUN apt-get update &&\
    apt install -y zsh &&\
    ln -sf /bin/zsh /bin/sh

# 指定字符集支持命令行输入中文（根据需要选择字符集）
ENV LC_ALL C.UTF-8
ENV LANG C.UTF-8
ENV LANGUAGE C.UTF-8

声明开发环境创建时机和其它准备工作：

#.coding-ci.yml
(**):
  branch.create:
    -   name: vscode
      services:
        -   vscode
      docker: 
        build: .tide/Dockerfile
      wework:
        title: 远程开发
      stages:
        -   name: ready
          type: vscode:go

更多内容详见：

使用技巧(快捷键冲突、数据漫游等)
开发实战(如何访问业务端口等)

问题反馈 >

2023-02-21最近更新

感谢反馈有用

感谢反馈没用