跳到主要内容

插件开发指南

语言​

插件代码语言推荐为 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);
}