GitHub Actions Utilities

A minimalistic utility package for developing GitHub Actions.

Key Features

• ES Module support
• Getting inputs and setting outputs
• Getting and setting states
• Setting environment variables and appending system paths
• Logging various kinds of messages

Installation

This project is available as an npm package under the name gha-utils:

npm install gha-utils

Usage Guide

Getting Inputs and Setting Outputs

GitHub Actions inputs can be retrieved using the getInput function, which returns a trimmed string or an empty string if the input is not specified. GitHub Actions outputs can be set using the setOutput or setOutputSync functions:

const input = getInput("input-name");

await setOutput("output-name", "a value");
setOutputSync("another-output-name", "another value");

Getting and Setting States

GitHub Actions states are useful for passing data between the pre, main, and post steps of the same GitHub Action. States can be set using the setState or setStateSync functions:

await setState("state-name", "a value");
setStateSync("another-state-name", "another value");

They can then be retrieved in the current or other steps using the getState function:

const state = getState("state-name");

Setting Environment Variables

Environment variables in GitHub Actions can be set using the setEnv or setEnvSync functions, which sets the environment variables in the current step and exports them to the next steps:

await setEnv("AN_ENV", "a value");
setEnvSync("ANOTHER_ENV", "another value");

Adding System Paths

System paths in the GitHub Actions environment can be added using the addPath or addPathSync functions, which prepends the given path to the system path. These functions are useful if an action is adding a new executable located in a custom path:

await addPath("path/to/an/executable");
addPathSync("path/to/another/executable");

Logging Messages

There are various ways to log messages in GitHub Actions, including logInfo for logging an informational message, logDebug for logging a debug message, logWarning for logging a warning message, logError for logging an error message, and logCommand for logging a command line message:

try {
  logInfo("an information");
  logDebug("a debug");
  logWarning("a warning");
  logCommand("command", "arg0", "arg1", "arg2");
} catch (err) {
  logError(err);
}

Grouping Logs

Logs can be grouped using the beginLogGroup and endLogGroup functions. All messages logged between these functions will be displayed as a group within a collapsible section:

beginLogGroup("a log group");
logInfo("this message is inside a group");
endLogGroup();

logInfo("this message is outside a group");

License

This project is licensed under the terms of the MIT License.

Copyright © 2024 Alfi Maulana