Coding-CI

Job

# Job介绍

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

# 内置任务

  • type:

    • type: String

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

  • options:

    • type: Object

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

  • optionsFrom:

    • type: String

    使用本地文件或 Coding Git 文件 url 的方式指定内置任务的相应参数。

options 和 optionsFrom 可以一起使用，也可以单独使用。

如果一起使用的话 options 中字段优先级高于 optionsFrom， 即相同字段，options 会覆写 optionsFrom 中的参数值。

示例：

name: install
type: INTERNAL_JOB_NAME
optionsFrom: ./options.json
options:
  key1: value1
  key2: value2

  // ./options.json
  {
    "key1": "value1",
    "key2": "value2",
  }

# 脚本任务

- name: install
  script: npm install

  • script:

    • type: Array<String> | String

    指定该步骤所要执行的 shell 脚本。数组会默认使用 && 连接。

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

  • image:

    • type: String

    指定脚本执行环境。

示例：

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

# 插件任务

不同于以上两类任务，插件任务 具有执行环境更自由的特点。 而且更易在团队、公司内外分享，甚至可以跨 CI 复用。

插件任务 通过向 ENTRYPOINT 传递环境变量的方式，来达到隐藏内部实现的目的。

注意：通过 imports、env 等参数设置的自定义环境变量不会传递给插件，但可以用在 settings、args中的变量替换。CNB 系统环境变量依然会传递给插件

  • name:

    • type: String

    指定 Stage 名称。

  • image:

    • type: String

    镜像的完整路径。

  • settings:

    • type: Object

    指定该镜像任务执行所需的参数。按照镜像提供方的文档填写即可。也可以通过 $VAR 或者 ${VAR} 取到环境变量。

  • settingsFrom:

    • type: String

      指定 Git 仓库文件路径（单个字符串或者数组），会读取此文件作为 settings 参数。

      支持的文件格式：

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

      优先级：

      • 如遇到参数重复的情况，后面的配置会覆盖前面的。
      • settings 和 settingsFrom 中参数重复，优先使用 settings 中的值。

# settingsFrom 权限控制

  • 同时限制 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 job.settings-from="https://xxx.com/xxx/xxx/blob/master/settings.json"

# 示例

with imports：

- name: npm publish
  image: plugins/npm
  imports: https://xxx/npm.json
  settings:
    username: $NPM_USER
    password: $NPM_PASS
    email: $NPM_EMAIL
    registry: https://mirrors.xxx.com/npm/
    folder: ./

{
  "username": "xxx",
  "password": "xxx",
  "email": "xxx@emai.com",
  "allow_slugs": [
    "coding-ci/**/**"
  ],
  "allow_images": [
    "plugins/npm"
  ]
}

with settingsFrom：

- name: npm publish
  image: plugins/npm
  settingsFrom: https://xxx/npm-settings.json
  settings:
    # username: $NPM_USER
    # password: $NPM_PASS
    # email: $NPM_EMAIL
    registry: https://mirrors.xxx.com/npm/
    folder: ./

{
  "username": "xxx",
  "password": "xxx",
  "email": "xxx@emai.com",
  "allow_slugs": [
    "coding-ci/coding-ci"
  ],
  "allow_images": [
    "plugins/npm"
  ]
}

# name

  • type: String

指定 Job 名称。

# ifModify

  • type: Array<String> | String

同 Stage ifModify。只对当前 Job 生效。

# ifNewBranch

  • type: Boolean
  • default: false

同 Stage ifNewBranch。只对当前 Job 生效。

# if

  • type: Array<String> | String

同 Stage if。只对当前 Job 生效。

# breakIfModify

  • type: Boolean
  • default: false

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

# skipIfModify

  • type: Boolean
  • default: false

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

# env

  • type: Object

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

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

# imports

  • type: Array<String> | String

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

# exports

  • type: Object

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

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

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

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

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

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

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

比如：如何将脚本中自定义变量传递到环境变量，进而影响后续构建任务。

有如下两种方式：

  • 可以通过 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]"

然后通过 exports 导出：

name: add vars into result
script: node set-output.js
exports:
  key: KEY

工作原理：

通过如下约定的格式：

##[set-output key=value]

CI 会从标准输出流里识别变量，自动放入 result 对象中，再通过 exports 声明到后续任务环境变量中。

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

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

TIP

受限于系统环境变量值长度限制，过大的变量值无效。可写入文件中自行解析。

CI 解析 set-output 变量时会忽略大于等于 100KB 的变量值。

  • 内置任务的 result

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

# timeout

  • type: Number | String

设置单个任务的超时时间，默认为 1 小时，最大不能超过 12 小时。

对 script-job 和 image-job 有效。

同时支持以下单位：

  • ms: 毫秒(默认)
  • s : 秒
  • m : 分钟
  • h : 小时
name: timeout job
script: sleep 1d
timeout: 100s #任务将在100秒后超时退出

详见 超时策略

# allowFailure

  • type: Boolean | String
  • default: false

为 true 表示本步骤如果失败，也不会影响接下来流程的执行，并且不会影响最后的结果。

值为 String 类型时可以读取环境变量

# lock

  • type: Object | Boolean

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

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

  • lock.key

    • type: String

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

  • lock.expires

    • type: Number
    • default: 3600(一小时)

锁过期时间，过期后自动释放锁，单位“秒”。

  • lock.wait

    • type: Boolean
    • default: false

锁被占用是否等待。

  • lock.timeout

    • type: Number
    • default: 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

  • type: Number
  • default: 0

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

# type

  • type: String

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

# options

  • type: Object

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

# optionsFrom

  • type: String

使用本地文件的方式指定内置任务的相应参数。

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

# script

  • type: Array<String> | String

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

# commands

  • type: Array<String> | String

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

# image

  • type: Object | String

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

  • image.name:

    • type: String

    镜像名。如node:14。

  • image.dockerUser:

    • type: String

    指定 docker 用户名，用于拉取指定的镜像。若指定 image 为非公开镜像则必须指定，否则会出现没有权限拉取镜像的情况。

  • image.dockerPassword:

    • type: String

    指定 docker 用户密码，用于拉取指定的镜像。若指定 image 为非公开镜像则必须指定，否则会出现没有权限拉取镜像的情况。

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

# settings

  • type: Object

指定该镜像任务执行所需的参数。详细插件任务介绍

# settingsFrom

  • Array<String> | String

从文件中读取该镜像任务执行所需的参数。详细插件任务介绍

# args

  • Array<String>

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

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

将执行

docker run plugins/npm ls

# 任务退出码

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

← include →