插件开发指南
本文档介绍如何使用 JavaScript/TypeScript 编写插件核心代码，包括参数获取、日志输出、状态反馈、结果输出和 post 后处理。
插件代码语言推荐为 TypeScript。
编写核心代码
插件的核心逻辑可使用 JavaScript/TypeScript 编写。如需使用其他语言的脚本，请通过 JavaScript/TypeScript 调用执行。
开发建议： 先实现最核心的功能，确保插件能够基本运行，然后逐步迭代增加更多功能。
示例：使用 Node.js 开发插件
import core from '@actions/core';
try {
const myInput = core.getInput('myInput'); // 获取插件输入
const ref = process.env['ATOMGIT_REF']; // 获取系统变量
const result = `Hello ${pipelineId}, ${myInput}!`; // 插件核心逻辑
} catch (error) {
core.setFailed(`Action failed with error: ${error.message}`);
}
参数获取方式：
| 方法 | 用途 |
|---|---|
process.env[] | 获取环境变量参数 |
core.getInput() | 获取插件输入参数 |
推荐工具包
GitHub Actions Toolkit 是开发过程中推荐使用的三方工具包，提供 @actions/core、@actions/io、@actions/exec、@actions/glob、@actions/http-client 等模块，可辅助插件代码开发。
日志输出
使用 @actions/core 库输出日志：
const core = require('@actions/core');
core.info('Starting action...');
core.warning('This is a warning message');
core.error('This is an error message');
| 方法 | 用途 |
|---|---|
core.info() | 普通日志信息 |
core.warning() | 警告信息 |
core.error() | 错误信息 |
执行状态反馈
- 正常执行完成：任务 process 返回
0 - 出现异常或错误：通过
core.setFailed()修改进程返回，调度框架捕获到非 0 返回则判定任务失败
结果输出和收集
插件任务通过系统变量 $ATOMGIT_OUTPUT 定义插件运行时 output 收集文件路径，输出至该文件的内容会被系统回收至流水线 step、job、pipeline 级 output 结果归档。
方式一：通过日志关键字实时输出
该方式会将 output 实时 在流水线上收集并呈现，如遇相同 key 则覆盖，不同 key 追加。
log.info(`::set-output var=${outputkey}:${outputvalue}`)
方式二：批量写入 output（推荐）
将需要收集的 output 统一写入 $ATOMGIT_OUTPUT 定义的官方路径，并在插件 执行成功后统一上报：
export async function writeOutputContext(data: string) {
const filePath = core.getInputForEnv("ATOMGIT_OUTPUT");
log.info("outputFilePath is " + filePath);
if (!filePath) {
log.error(ErrorCode.INVALID_PARAM, {
cause: `Failed to get the upload report path: ATOMGIT_OUTPUT`,
causeZh: `获取输出路径失败: ATOMGIT_OUTPUT`,
});
return;
}
fs.appendFile(filePath, data, async (err) => {
if (err) {
log.error(ErrorCode.LOCAL_ERROR, {
cause: `Failed to write the report file.`,
causeZh: `写入output上报文件失败`,
});
return;
} else {
log.info("File written successfully!");
}
});
}
插件Summary报告输出
您可以为每个 Job（作业）输出自定义的 Markdown 格式内容，这些内容将直接显示在 Workflow运行记录的摘要页面上。利用 Job 摘要，您可以对特定内容（如测试结果）进行可视化展示和分组。这样一来，查看 Workflow 运行结果的人员无需逐行翻阅日志，就能快速掌握本次运行的关键信息（例如错误或失败提示）。 您可以将 Step（步骤）中生成的 Markdown 内容追加写入到 ATOMGIT_STEP_SUMMARY 环境变量所指向的文件中。需要注意的是，ATOMGIT_STEP_SUMMARY 对应的临时文件对于每个 Step 都是独立且唯一的。 当一个 Job 执行完成后，该 Job 下所有 Step 生成的摘要将被按顺序拼接为一个统一的 Job 摘要，并展示在 Workflow 的运行摘要页面上。如果一次运行中包含多个生成了摘要的 Job，这些摘要将按照 Job 的完成时间顺序进行展示。
添加 Job 摘要示例：
echo "### Hello world! :rocket:" >> $ATOMGIT_STEP_SUMMARY
多行 Markdown 内容
如果需要写入多行 Markdown 内容，您可以在当前 Step 中连续使用 >> 追加操作符。每次执行追加操作时，系统都会自动添加一个换行符。
多行 Markdown 内容示例：
- name: Generate list using Markdown
run: |
echo "This is the lead in sentence for the list" >> $ATOMGIT_STEP_SUMMARY
echo "" >> $ATOMGIT_STEP_SUMMARY # 这是一个空行
echo "- Lets add a bullet point" >> $ATOMGIT_STEP_SUMMARY
echo "- Lets add a second bullet point" >> $ATOMGIT_STEP_SUMMARY
echo "- How about a third one?" >> $ATOMGIT_STEP_SUMMARY
插件执行后处理 (post)
post 脚本（推荐命名为 post.js）是提供给调度服务 post 调用的逻辑，用于清理现场、执行善后逻辑等。
触发机制：
| 触发方式 | 说明 |
|---|---|
| 主动停止流水线 | 用户点击停止流水线，由调度服务主动调用 |
| 插件完成后自然调用 | 需插件开发者在 main 中主动监听终止信号并调用 |
示例 — 在 main 中监听终止信号：
import {post} from "./stop";
async function run() {
// 捕获 SIGINT 信号
process.on('SIGINT', () => {
post();
process.exit(0);
});
// 插件主逻辑...
log.info("process has been started，press 'Ctrl C' to stop.");
setInterval(() => {
log.info("process running...");
}, 1000);
}