Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/threeal/gha-utils
A minimalistic utility package for developing GitHub Actions.
https://github.com/threeal/gha-utils
github github-actions javascript node nodejs typescript utility
Last synced: 2 months ago
JSON representation
A minimalistic utility package for developing GitHub Actions.
- Host: GitHub
- URL: https://github.com/threeal/gha-utils
- Owner: threeal
- License: mit
- Created: 2024-08-07T14:49:55.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-11-06T12:10:46.000Z (2 months ago)
- Last Synced: 2024-11-06T13:21:04.930Z (2 months ago)
- Topics: github, github-actions, javascript, node, nodejs, typescript, utility
- Language: TypeScript
- Homepage: https://threeal.github.io/gha-utils/
- Size: 402 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Actions Utilities
A minimalistic utility package for developing [GitHub Actions](https://github.com/features/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](https://www.npmjs.com/) package under the name [gha-utils](https://www.npmjs.com/package/gha-utils):
```sh
npm install gha-utils
```
## Usage Guide
### Getting Inputs and Setting Outputs
GitHub Actions inputs can be retrieved using the [`getInput`](https://threeal.github.io/gha-utils/functions/getInput.html) 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`](https://threeal.github.io/gha-utils/functions/setOutput.html) or [`setOutputSync`](https://threeal.github.io/gha-utils/functions/setOutputSync.html) functions:
```ts
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`](https://threeal.github.io/gha-utils/functions/setState.html) or [`setStateSync`](https://threeal.github.io/gha-utils/functions/setStateSync.html) functions:
```ts
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`](https://threeal.github.io/gha-utils/functions/getState.html) function:
```ts
const state = getState("state-name");
```
### Setting Environment Variables
Environment variables in GitHub Actions can be set using the [`setEnv`](https://threeal.github.io/gha-utils/functions/setEnv.html) or [`setEnvSync`](https://threeal.github.io/gha-utils/functions/setEnvSync.html) functions, which sets the environment variables in the current step and exports them to the next steps:
```ts
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`](https://threeal.github.io/gha-utils/functions/addPath.html) or [`addPathSync`](https://threeal.github.io/gha-utils/functions/addPathSync.html) 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:
```ts
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`](https://threeal.github.io/gha-utils/functions/logInfo.html) for logging an informational message, [`logDebug`](https://threeal.github.io/gha-utils/functions/logDebug.html) for logging a debug message, [`logWarning`](https://threeal.github.io/gha-utils/functions/logWarning.html) for logging a warning message, [`logError`](https://threeal.github.io/gha-utils/functions/logError.html) for logging an error message, and [`logCommand`](https://threeal.github.io/gha-utils/functions/logCommand.html) for logging a command line message:
```ts
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`](https://threeal.github.io/gha-utils/functions/beginLogGroup.html) and [`endLogGroup`](https://threeal.github.io/gha-utils/functions/endLogGroup.html) functions. All messages logged between these functions will be displayed as a group within a collapsible section:
```ts
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](./LICENSE).
Copyright © 2024 [Alfi Maulana](https://github.com/threeal)