pipeline-plugin-development

流水线插件开发完整指南

模块定位: 本指南详细介绍蓝盾（BK-CI）流水线插件的开发规范、配置方法、多语言实现示例、发布流程和调试技巧，帮助开发者快速上手插件开发。

一、插件开发概述

1.1 什么是流水线插件

流水线插件（Atom）是蓝盾流水线中的最小执行单元，用于完成特定的构建任务，如代码拉取、编译、测试、部署等。

1.2 支持的开发语言

语言	推荐度	SDK
Java	⭐⭐⭐⭐⭐	java-atom-sdk
Python	⭐⭐⭐⭐	python-atom-sdk
NodeJS	⭐⭐⭐	@tencent/nodejs_atom_sdk
Golang	⭐⭐⭐	golang-atom-sdk

1.3 插件开发流程

┌─────────────────────────────────────────────────────────────────────────┐
│                        插件开发完整流程                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  1. 初始化插件          2. 开发插件           3. 发布插件                │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐           │
│  │ 登录工作台    │  ──► │ 编写 task.json│ ──► │ 提交构建     │           │
│  │ 新增插件      │      │ 开发业务逻辑  │      │ 测试验证     │           │
│  │ 克隆代码库    │      │ 本地调试      │      │ 审核发布     │           │
│  └──────────────┘      └──────────────┘      └──────────────┘           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

二、task.json 配置规范

2.1 整体结构

{
    "atomCode": "myAtom",           // 插件唯一标识（必填）
    "defaultLocaleLanguage": "zh_CN", // 默认语言（非必填）
    "execution": {                   // 执行配置（必填）
        "language": "python",
        "demands": [],
        "target": "demo"
    },
    "inputGroups": [],               // 输入字段分组（非必填）
    "input": {},                     // 输入字段定义（必填）
    "output": {},                    // 输出字段定义（非必填）
    "config": {}                     // 插件控制特性（非必填）
}

注意: task.json 内容长度最大为 64KB

2.2 execution 执行配置

属性名	说明	格式	必填
language	开发语言	字符串	是
target	执行入口命令	字符串	是
demands	执行前置依赖命令	数组	否
runtimeVersion	运行时版本	字符串	否
finishKillFlag	执行完成后是否杀进程	布尔	否
os	操作系统相关配置	数组	否

2.2.1 runtimeVersion 配置值

语言	配置值	备注
python	python2	默认
python	python3	推荐
nodejs	10.* ~ 18.*	默认 10.*
java	8	默认
java	17	新版本

2.2.2 os 跨平台配置示例

{
    "execution": {
        "language": "golang",
        "os": [
            {
                "osName": "linux",
                "osArch": "amd64",
                "target": "./app",
                "demands": [],
                "defaultFlag": true
            },
            {
                "osName": "windows",
                "osArch": "386",
                "target": "./app.exe",
                "demands": [],
                "defaultFlag": false
            },
            {
                "osName": "darwin",
                "osArch": "arm64",
                "target": "./app",
                "demands": [],
                "defaultFlag": false
            }
        ]
    }
}

2.3 input 输入字段配置

2.3.1 支持的 UI 组件类型

组件 type	组件名称	获取到的值格式
vuex-input	单行文本框	字符串
vuex-textarea	多行文本框	字符串
atom-ace-editor	代码编辑框	字符串
selector	下拉框（只选不输入）	单选: 字符串; 多选: ["str1", "str2"]
select-input	可输入下拉框	同上
devops-select	可输入下拉框（仅变量）	同上
atom-checkbox-list	复选框列表	["id1", "id2"]
atom-checkbox	复选框（布尔）	"true" 或 "false"
enum-input	单选 Radio	字符串
time-picker	日期选择器	字符串
staff-input	人名选择器（项目成员）	字符串
company-staff-input	人名选择器（公司成员）	字符串
tips	提示信息	无
parameter	不定参数列表	JSON 字符串
dynamic-parameter	动态参数列表	JSON 字符串
dynamic-parameter-simple	动态参数（简易版）	JSON 字符串

2.3.2 输入字段公共属性

属性名	说明	格式	必填
label	中文名	字符串	是
type	组件类型	字符串	是
default	默认值	根据组件类型	否
placeholder	占位提示	字符串	否
groupName	所属分组	字符串	否
desc	字段说明	字符串	否
required	是否必填	布尔	否
disabled	是否禁用	布尔	否
hidden	是否隐藏	布尔	否
isSensitive	是否敏感信息	布尔	否
rely	条件显示/隐藏	对象	否
rule	值校验规则	对象	否

2.3.3 完整输入字段示例

{
    "input": {
        "repositoryUrl": {
            "label": "代码库地址",
            "type": "vuex-input",
            "placeholder": "请输入 Git 仓库地址",
            "desc": "支持 HTTP/HTTPS/SSH 协议",
            "required": true,
            "rule": {
                "regex": "^(https?|git)://"
            }
        },
        "branch": {
            "label": "分支",
            "type": "select-input",
            "default": "master",
            "optionsConf": {
                "searchable": true,
                "multiple": false,
                "url": "/repository/api/user/repositories/{projectId}/branches",
                "paramId": "name",
                "paramName": "name"
            }
        },
        "enableCache": {
            "label": "",
            "type": "atom-checkbox",
            "text": "启用缓存",
            "default": true
        },
        "buildType": {
            "label": "构建类型",
            "type": "enum-input",
            "default": "release",
            "list": [
                {"label": "Debug", "value": "debug"},
                {"label": "Release", "value": "release"}
            ]
        },
        "advancedOptions": {
            "label": "高级选项",
            "type": "vuex-input",
            "rely": {
                "operation": "AND",
                "expression": [
                    {"key": "enableCache", "value": true}
                ]
            }
        }
    }
}

2.4 output 输出字段配置

{
    "output": {
        "buildResult": {
            "type": "string",
            "description": "构建结果",
            "isSensitive": false
        },
        "artifactPath": {
            "type": "artifact",
            "description": "构建产物路径"
        },
        "reportHtml": {
            "type": "report",
            "description": "测试报告"
        }
    }
}

输出类型说明:

类型	说明	限制
string	字符串变量	长度不超过 4KB
artifact	构件文件	自动归档到仓库
report	报告文件	支持 HTML 渲染

2.5 config 插件控制特性

{
    "config": {
        "canPauseBeforeRun": false,
        "defaultTimeout": 60,
        "defaultFailPolicy": "MANUALLY_CONTINUE",
        "defaultRetryPolicy": ["AUTO_RETRY"],
        "retryTimes": 3
    }
}

2.6 内置变量

变量名	说明
{projectId}	项目英文 ID
{pipelineId}	流水线 ID
{buildId}	构建 ID

三、多语言开发示例

3.1 Python 插件开发

3.1.1 目录结构

my-python-atom/
├── task.json
├── setup.py
├── requirements.txt
└── demo/
    ├── __init__.py
    └── command_line.py

3.1.2 task.json

{
    "atomCode": "myPythonAtom",
    "execution": {
        "language": "python",
        "demands": [],
        "target": "demo"
    },
    "input": {
        "inputDemo": {
            "label": "输入示例",
            "type": "vuex-input",
            "required": true
        }
    },
    "output": {
        "outputDemo": {
            "type": "string",
            "description": "输出示例"
        }
    }
}

3.1.3 setup.py

from setuptools import setup, find_packages

setup(
    name="myPythonAtom",
    packages=find_packages(),
    install_requires=["python-atom-sdk"],
    entry_points={
        "console_scripts": [
            "demo = demo.command_line:main"
        ]
    }
)

3.1.4 command_line.py

# -*- coding: utf-8 -*-
import python_atom_sdk as sdk

def main():
    sdk.log.info("插件开始执行")
    
    # 获取输入参数
    input_params = sdk.get_input()
    input_demo = input_params.get("inputDemo", "")
    sdk.log.info(f"输入参数: {input_demo}")
    
    # 业务逻辑处理
    result = f"处理结果: {input_demo}"
    
    # 设置输出
    output_data = {
        "status": sdk.status.SUCCESS,
        "message": "执行成功",
        "errorCode": 0,
        "type": sdk.output_template_type.DEFAULT,
        "data": {
            "outputDemo": {
                "type": sdk.output_field_type.STRING,
                "value": result
            }
        }
    }
    sdk.set_output(output_data)
    
    sdk.log.info("插件执行完成")
    exit(0)

if __name__ == "__main__":
    main()

3.2 Java 插件开发

3.2.1 目录结构

my-java-atom/
├── task.json
├── pom.xml
├── settings.xml
└── src/main/
    ├── java/com/example/atom/
    │   ├── AtomParam.java
    │   └── DemoAtom.java
    └── resources/META-INF/services/
        └── com.tencent.bk.devops.atom.spi.TaskAtom

3.2.2 task.json

{
    "atomCode": "myJavaAtom",
    "defaultLocaleLanguage": "zh_CN",
    "execution": {
        "language": "java",
        "minimumVersion": "1.8",
        "demands": [],
        "target": "java -jar myJavaAtom-jar-with-dependencies.jar"
    },
    "input": {
        "desc": {
            "label": "描述",
            "type": "vuex-input",
            "placeholder": "请输入描述信息",
            "required": true
        }
    },
    "output": {
        "testResult": {
            "type": "string",
            "description": "执行结果"
        }
    }
}

3.2.3 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>com.tencent.bk.devops.atom</groupId>
        <artifactId>sdk-dependencies</artifactId>
        <version>1.0.0</version>
    </parent>

    <artifactId>myJavaAtom</artifactId>
    <version>1.0.0</version>

    <properties>
        <sdk.version>1.1.58</sdk.version>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.tencent.bk.devops.atom</groupId>
            <artifactId>java-atom-sdk</artifactId>
            <version>${sdk.version}</version>
        </dependency>
    </dependencies>

    <build>


---

*Content truncated.*