声明文件

声明文件需命名为 qciplugin.yml;文件内容需包含插件的 id, 名称, 参数, 执行入口等配置信息。插件执行器将读取信息并上传至 CODING 后自动生成插件运行所需的 UI 表单, 在运行时也需要读取信息并作为执行参考。

示例

# 插件版本, 用于定义插件包的版本, 做版本管理使用
version: '1.0'

# 插件ID
id: plugin_demo

# 插件中文名称
name: 插件 demo

# 插件描述
description: 插件 demo 描述

# 插件分类
category: build

# 声明插件使用的参数
variables:
  - name: arg1
    type: text
    label: 参数1
    help: this argument help description。
    required: true
  - name: arg2
    ...
  - name: env1
    ...

# 执行入口配置, 声明如何运行插件脚本
entry:
  # 插件执行依赖
  install:
    - $QCI_PLUGIN_EXECUTABLE -m pip install -r $QCI_PLUGIN_RUNTIME/requirements.txt --user

  # 插件环境变量
  env:
    ENV: $env1

  # 插件启动入口
  start: $QCI_PLUGIN_EXECUTABLE $QCI_PLUGIN_RUNTIME/run.py $arg1 $arg2 --status $QCI_PLUGIN_RUNTIME/status.json

  # 插件状态文件
  status: $QCI_PLUGIN_RUNTIME/status.json

基本信息

插件的基本信息包括:

  • version: 插件支持版本管理, 版本号由开发者自行维护, 必须是字符串

  • id: 插件唯一标识, 英文 + 下划线

  • name: 插件名称, 请使用中文名称, 会作为流水线 UI 配置的插件名

  • description (非必填): 插件简介, 请简短介绍插件的用途, 会作为流水线 UI 配置的插件 Tips. 如需要展示更多插件相关的文档, 请参考: 插件文档 一节

  • category: 插件分类, 会在流水线 UI 配置中, 进行分组, 如果填写不在以下分类的值, 可能会导致 UI 配置找不到插件

    • build: 编译
    • test: 测试
    • security: 安全
    • release: 发布部署
    • message: 消息通知
    • scm: 代码管理
    • other: 其他
  • author:插件作者,非必填

variables

插件参数 variables 选项是描述流水线的 UI 配置时表单的渲染参考,插件执行器在启动时会根据选项处理参数。

⚠️ 插件参数不等同于开发者自身脚本参数,虽然大部分情况下插件参数与执行参数相同。具体差别可以参考插件运行机制

variables 选项是一个数组,使用 yaml 格式描述为:

variables:
  # 请注意 "-" 以及缩进
  - name: arg1
    type: text
    label: 参数1
    help: this argument help description。
    required: true
  - name: arg2
    ...
  - name: env1
    ...

variables 每个元素可以有如下属性:

  • name(string): 参数名, 必须是 英文名 + 数字 + 下划线, 作为 UI 配置以及执行器使用的参数名, 在没有配置 resolve 参数时也默认为传入给插件脚本的参数名。

  • label(string): 参数中文名, 用于 UI 配置时展示。

  • type(string): 参数类型, 用于 UI 配置时渲染不同的 UI, 同时也根据此类型, 决定执行器传入插件脚本的行为:

    • text: 文本类型, UI 默认使用单行文本框
    • choice: 选项类型, 使用 choice 时,需跟 options 参数一并使用, UI 默认使用下拉框
    • bool: 布尔类型, UI 使用复选框
  • widget(string): UI 组件类型, 除了 type 的默认 UI 类型外, 还可以根据 widget 的不同, 设定不同的组件

    • type == text, 可以支持的 widget 参数:

      • input(默认): 单行文本框
      • textarea: 多行文本框
      • multiline-textarea: (特殊)多行文本框, 文本框每一行是一个参数, 即参数用换行符分隔
      • userchooser: 用户选择器, 可使用 options 设置选项
    • type == choice, 可以支持的 widget 参数:

      • select(默认): 下拉框
      • checkbox: 复选框
      • radio: 单选框
      • remote-select: 远程下拉框
    • type == bool, 不支持 widget 参数, UI 组件会生成一个复选框

  • required(可选, boolean): 是否必填

  • default(可选, string | boolean): 默认值, 注意: 只能使用 字符串(type == text|choice) 和 布尔(type == bool) 类型

  • placeholder(可选, string): UI 组件的 placeholder, 仅在 UI 为文本框时生效

  • help(可选, string): 帮助信息

  • options(可选, object | array): UI 组件选项, 根据 type 与 widget 的不同, 可以有如下的配置

    • type == choice 需要配置每个选项的 label 和 value, 示例:
options:
  - label: label1
    value: value1
  - label: label2
    value: value2
  • type = choice && widget = remote-select 需要配置,从数据源动态获取 option 选项, 示例:
# 返回数据 { code:0, msg:'success', data:[{id:1,name:'选项一'},{id:2,name:'选项二' }]}
# 返回数据中三层以内的数组结构会被识别为 options 数据
# 注意: 接口需要支持跨域调用
options:
  url: "http://xxx.com?searchKey=test" | "/api/user/tencent/project/{project_id}/cd/flows" | "/xxx"  # 数据源地址
  valueKey: "id" # 下拉选项 value 在返回数据中的key
  textKey: "name" # 选项 text 在返回数据中的key
  • type == text && widget == userchooser 可选配置, 示例:
options:
  singleton: true / false (是否单选/复选)
  useEnv: true / false (是否可以输入环境变量)
  • resolve(可选, string | null): 调整执行器传入给脚本参数名, 默认是长参数, 即: –{name}, 可由开发者自行调整(由于可以随意定制字符串, 请注意命令行参数规范):

    • 长参数: –foo, 这是默认设置
    • 短参数: -f
    • 无参数: ~ (注意是一个波浪号), 传入参数会变化, 具体参考 type 与 传入参数值的关系中 bool 类型一节
  • advanced(可选, boolean): 是否是高级选项, advanced 设置成 true, 前端会将此字段放到高级选项栏里, 只有用户展开高级选项才能看到 , 适合插件参数太多, 部分参数可以选填的情况。

entry

插件执行入口 entry 选项是用于描述插件如何执行插件脚本的配置。

entry 选项的数据结构为字典,使用 yaml 格式描述为:

# 执行入口配置, 声明如何运行插件脚本
entry:
  # 插件执行依赖
  install:
    - $QCI_PLUGIN_EXECUTABLE -m pip install -r $QCI_PLUGIN_RUNTIME/requirements.txt --user

  # 插件环境变量
  env:
    ENV: $env1

  # 插件启动入口
  start: $QCI_PLUGIN_EXECUTABLE $QCI_PLUGIN_RUNTIME/run.py $arg1 $arg2 --status $QCI_PLUGIN_RUNTIME/status.json

  # 插件状态文件
  status: $QCI_PLUGIN_RUNTIME/status.json
  • install(array): 一个 数组, 声明插件脚本运行前需要执行的命令, 可以使用 variables 定义的参数占位符 $var.
  • start(string): 声明插件脚本运行命令行, 可以使用 variables 定义的参数占位符 $var, 如果有固定参数可以一并写入.
  • env(可选, object): 插件环境变量, 可以使用 variables 定义的占位符 $var, 可以让 variables 里定义的参数通过环境变量提供给插件脚本, 而不是参数.
  • status(可选, string): 插件脚本可以写入 status.json 决定程序是否执行成功, 如没有此节点, 会根据程序的退出码判定。

关于插件如何运行可以点击了解详情

如何使用占位符

qciplugin.yml 里 install,start 节点均可以使用占位符做参数传入。占位符由 variables 定义的参数决定,没有声明 variabels 则占位符无效。占位符的行为会与 variables 中 type 和 widget 有直接关系。

  • type == text 时
# 定义
variables:
  - name: arg1
    type: text

entry:
  start: python run.py $arg1

----

# 启动命令
qci-plugin myplugin --arg1 "hello world"
# 实际命令
python run.py --arg1 "hello world"

----

# 不传 arg1 时, 不会给脚本传入 --arg1
# 启动命令, 不传 arg1
qci-plugin myplugin
# 实际命令, 不传 arg1
python run.py
  • type == text && widget == multiline-textarea 时,参数为多项参数。使用 python 开发时可以参考文档。
# 定义
variables:
  - name: arg1
    type: text
    widget: multiline-textarea  # 注意这里

entry:
  start: python run.py $arg1

----

# 启动命令
qci-plugin myplugin --arg1 "foo" "bar" "baz"
# 实际命令
python run.py --arg1 "foo" "bar" "baz"
  • type == choice && widget == select|radio|remote-select 时
# 定义
variables:
  - name: arg1
    type: choice
    options:
      - label: label1
        value: value1
      - label: label2
        value: value2


entry:
  start: python run.py $arg1

----

# 启动命令
qci-plugin myplugin --arg1 "hello world"
# 实际命令
python run.py --arg1 "hello world"
  • type == choice && widget == checkbox(复选) 时, 参数是多项参数, python 开发时: 参考, 使用 nargs=(+|*)
# 定义
variables:
  - name: arg1
    type: choice
    options:
      - label: label1
        value: value1
      - label: label2
        value: value2


entry:
  start: python run.py $arg1

----

# 启动命令
qci-plugin myplugin --arg1 "value1" "value2"
# 实际命令
python run.py --arg1 "value1" "value2"
  • type == bool 时, 根据参数, 直接标记, python 开发时: 参考 中将 action=”store_true”, 即可获取到正确的参数值
# 定义
variables:
  - name: arg1
    type: bool

entry:
  start: python3 run.py $arg1

----

# 启动命令, 注意不带参数值
qci-plugin myplugin --arg1
# 实际命令, 注意不带参数值
python run.py --arg1

----

# 启动命令, 参数为 false, 不传 arg1
qci-plugin myplugin
# 实际命令, 参数为 false, 不传 arg1
python run.py

如果 resolve 设置为 ~, bool 传入值有如下变化:

# 定义
variables:
  - name: arg1
    type: bool
    resolve: ~

entry:
  start: python3 run.py $arg1

----
# arg1 = true 命令行传入 1
python run.py 1
# arg1 = false 命令行传入 0
python run.py 0

如何使用 env 环境变量

entry 中允许开发者定义用户输入的值通过环境变量传入, 便于开发者隐藏不希望通过命令行参数传入的值, 同样可以使用 $var 占位符:

variables:
  - name: arg1
    ...
  - name: arg2
    ...

entry:
  env:
    MY_ENV: $arg2
  start: python run.py $arg1

----
# 插件启动命令为:
qci-plugin myplugin --arg1 value1 --arg2 value2

# 执行的命令行为:
python run.py --arg1 value1

而 arg2 的值, 通过环境变量 MY_ENV 获得。

关于 status

status.json 文件允许开发者自行写入状态来覆写程序自身的退出码:

  • 没有 status, 脚本是否正常执行, 是由程序的退出码控制:
    0: 正常
    非 0: 错误

  • 有 status 则以 status 为准

在插件中写入 status.json,将其写入插件安装目录,建议按下面示例显式的使用 status 的路径:

id: myplugin

variables:
  - name: input
    type: text
    label: 输入内容
    required: true

entry:
  start: $QCI_PLUGIN_EXECUTABLE $QCI_PLUGIN_RUNTIME/run.py $input --status $QCI_PLUGIN_RUNTIME/status.json

  status: $QCI_PLUGIN_RUNTIME/status.json

在 start 节点中, 通过参数传入 status.json ,脚本读取参数来指定写入路径并在 status 节点中指定该路径。插件安装目录不等同于集成目录,若隐式写 status.json,虽然插件也可以读取, 但集成时容易出现并发冲突和重名问题

若想了解更多 status 信息, 请点击阅读状态上报

上一篇开发指引
最近更新
感谢反馈有用
感谢反馈没用

在阅读中是否遇到以下问题?

您希望我们如何改进?