云原生构建

Job

# Job介绍

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

# 内置任务

  • type:

    • type: String

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

  • options:

    • type: Object

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

  • optionsFrom:

    • Array<String> | String

    指定本地或 Git 仓库文件路径，加载为内置任务参数。与 imports 参数类似，配置 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:20
  script: npm install

# 插件任务

插件即 Docker 镜像，也可称为镜像任务。

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

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

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

  • name:

    • type: String

    指定 Job 名称。

  • image:

    • type: String

    镜像的完整路径。

  • settings:

    • type: Object

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

  • settingsFrom:

    • type: Array<String> | String

      指定本地或 Git 仓库文件路径，加载为插件任务参数。

      优先级：

      • 如遇到参数重复的情况，后面的配置会覆盖前面的。
      • settings 中同名字段优先级高于 settingsFrom。

引用配置文件权限控制参考 配置文件引用鉴权。

示例：

同时限制 images 和 slugs：

allow_slugs:
  - a/b
allow_images:
  - a/b

仅限制 images，不限制 slug：

allow_images:
  - a/b

settingsFrom 可以写在 Dockerfile 中：

FROM node:20

LABEL cnb.cool/settings-from="https://xxx/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": ["cnb/**/**"],
  "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": ["cnb/cnb"],
  "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 对象中

CI 会从标准输出流里识别 ##[set-output key=value] 格式的内容，自动放入 result 对象中，可通过 exports 导出为环境变量供后续任务使用。

若变量值包含换行符 \n，可对变量值进行 base64 或 escape 编码。

变量值若以 base64, 开始，云原生构建 会对 base64, 后面的内容做 base64 解码，否则会对变量值做 unescape 解码。

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

// test.js
const value = '测试字符串\ntest string';
// 输出 base64 编码的变量值
console.log(`##[set-output redline_msg_base64=base64,${Buffer.from(value, 'utf-8').toString('base64')}]`);

// 输出 escape 编码的变量值
console.log(`##[set-output redline_msg_escape=${escape(value)}]`)

main:
  push:
    - docker:
        image: node:20-alpine
      stages:
        - name: set output env
          script: node test.js
          # 将 test.js 输出的变量导出为环境变量
          exports:
            redline_msg_base64: BASE64_KEY
            redline_msg_escape: ESCAPE_KEY
        - name: echo env
          script:
            - echo "BASE64_KEY $BASE64_KEY"
            - echo "ESCAPE_KEY $ESCAPE_KEY"

使用 shell 直接 echo 的示例代码如下：

main:
  push:
    - stages:
        - name: set output env
          script: echo "##[set-output redline_msg_base64=base64,$(echo -n "测试字符串\ntest string" | base64)]"
          exports:
            redline_msg_base64: BASE64_KEY
        - name: echo env
          script:
            - echo -e "BASE64_KEY $BASE64_KEY"

不包含 \n 的变量值可直接输出

echo "##[set-output redline_msg=some value]"

提示

受限于系统环境变量值长度限制，过大的变量值无效。

CI 会忽略大于等于 100KB 的变量值。可写入文件中自行解析。

对于敏感信息，建议使用 read-file 内置任务。

  • 内置任务的 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: Array<String> | String

指定本地或 Git 仓库文件路径，加载为内置任务参数。与 imports 参数类似，配置 optionsFrom 为数组时，如遇到参数重复的情况，后面的配置会覆盖前面的。

options 同名字段优先级高于 optionsFrom。

# script

  • type: Array<String> | String

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

# commands

  • type: Array<String> | String

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

# image

  • type: Object | String

指定用哪个 Image 作为当前 Job 执行环境, 用于 docker image as env 或 docker image as plugins

  • image.name: String 镜像名，如 node:20。
  • image.dockerUser: String 指定 Docker 用户名，用于拉取指定的镜像。
  • image.dockerPassword: String 指定 Docker 用户密码，用于拉取指定的镜像。

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

# settings

  • type: Object

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

# settingsFrom

  • Array<String> | String

指定本地或 Git 仓库文件路径，加载为插件任务参数。与 imports 参数类似，配置 settingsFrom 为数组时，如遇到参数重复的情况，后面的配置会覆盖前面的。

详细插件任务介绍

# 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 →