Plugin Development Guide

This document introduces how to write plugin core code using JavaScript/TypeScript, including parameter acquisition, log output, status feedback, result output, and post-processing.

The recommended language for plugin code is TypeScript.

Writing Core Code

The core logic of the plugin can be written in JavaScript/TypeScript. If you need to use scripts in other languages, please call and execute them through JavaScript/TypeScript.

Development suggestion: First implement the most core functionality to ensure the plugin can run basically, then gradually iterate and add more features.

Example: Developing a Plugin with Node.js

import core from '@actions/core';

try {
  const myInput = core.getInput('myInput');           // Get plugin input
  const ref = process.env['ATOMGIT_REF'];      // Get system variable
  const result = `Hello ${pipelineId}, ${myInput}!`;  // Plugin core logic

} catch (error) {
  core.setFailed(`Action failed with error: ${error.message}`);
}

Methods for acquiring parameters:

Method	Purpose
process.env[]	Get environment variable parameters
core.getInput()	Get plugin input parameters

Recommended Toolkits

GitHub Actions Toolkit is a recommended third-party toolkit used during development, providing modules such as @actions/core, @actions/io, @actions/exec, @actions/glob, and @actions/http-client, which can assist in plugin code development.

Log Output

Use the @actions/core library to output logs:

const core = require('@actions/core');

core.info('Starting action...');
core.warning('This is a warning message');
core.error('This is an error message');

Method	Purpose
core.info()	General log information
core.warning()	Warning information
core.error()	Error information

Execution Status Feedback

• Normal execution completion: The task process returns 0
• Exception or error occurs: Modify the process return via core.setFailed(), and if the scheduling framework detects a non-zero return, it will determine the task as failed

Result Output and Collection

The plugin task defines the output collection file path during runtime via the system variable $ATOMGIT_OUTPUT. The content output to this file will be collected by the system into the pipeline step, job, and pipeline level output results.

Method One: Real-time Output via Log Keywords

This method collects and displays the output in real time on the pipeline. If the same key appears, it will be overwritten; different keys will be appended.

log.info(`::set-output var=${outputkey}:${outputvalue}`)

Method Two: Batch Write to Output (Recommended)

Collect all needed outputs uniformly into the official path defined by $ATOMGIT_OUTPUT, and report them uniformly after the plugin execution is successful:

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: `Getting the output path failed: ATOMGIT_OUTPUT`,
    });
    return;
  }
  fs.appendFile(filePath, data, async (err) => {
    if (err) {
      log.error(ErrorCode.LOCAL_ERROR, {
        cause: `Failed to write the report file.`,
        causeZh: `Failed to write the output reporting file`,
      });
      return;
    } else {
      log.info("File written successfully!");
    }
  });
}

Plugin Summary Report Output

You can output custom Markdown format content for each Job (job), which will be directly displayed on the summary page of the Workflow run record. Using the Job summary, you can visualize and group specific content (such as test results). This way, people viewing the Workflow run results do not need to scroll through logs line by line to quickly grasp the key information of this run (such as errors or failure messages). You can append the Markdown content generated in the Step to the file pointed to by the ATOMGIT_STEP_SUMMARY environment variable. It should be noted that the temporary file corresponding to ATOMGIT_STEP_SUMMARY is independent and unique for each Step. After a Job completes execution, the summaries generated by all Steps under this Job will be concatenated in order into a unified Job summary and displayed on the Workflow's run summary page. If multiple Jobs generate summaries in a single run, these summaries will be displayed in the order of the Job completion time.

Example of adding a Job summary:

echo "### Hello world! :rocket:" >> $ATOMGIT_STEP_SUMMARY

Multi-line Markdown Content

If you need to write multi-line Markdown content, you can use the >> append operator continuously within the current Step. Each time you perform an append operation, the system automatically adds a newline character.

Example of multi-line Markdown content:

- name: Generate list using Markdown
  run: |
    echo "This is the lead in sentence for the list" >> $ATOMGIT_STEP_SUMMARY
    echo "" >> $ATOMGIT_STEP_SUMMARY # This is an empty line
    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

Plugin Post-processing (post)

The post script (recommended to be named post.js) provides logic for the scheduling service to call after the plugin execution, used for cleaning up the site, executing post-processing logic, etc.

Trigger mechanism:

Trigger method	Description
Manually stop the pipeline	User clicks to stop the pipeline, triggered by the scheduling service
Plugin completes naturally	The plugin developer needs to actively listen for termination signals in main and call it

Example - Listening for termination signals in main:

import {post} from "./stop";

async function run() {
    // Capture SIGINT signal
    process.on('SIGINT', () => {
        post();
        process.exit(0);
    });

    // Plugin main logic...
    log.info("process has been started，press 'Ctrl C' to stop.");
    setInterval(() => {
        log.info("process running...");
    }, 1000);
}