声明文件
声明文件需命名为 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 == 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 定义的参数决定，没有声明 variables 则占位符无效。占位符的行为会与 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 信息, 请点击阅读状态上报。
2022-05-11最近更新在阅读中是否遇到以下问题？*
您希望我们如何改进？*
如果您希望得到回复，请留下您的邮箱地址。
