What is @actions/exec?
@actions/exec is an npm package designed to facilitate the execution of shell commands within GitHub Actions workflows. It provides a simple and flexible API to run commands, capture their output, and handle errors.
What are @actions/exec's main functionalities?
Basic Command Execution
This feature allows you to execute basic shell commands. In this example, the 'echo' command is used to print 'Hello, world!' to the console.
const exec = require('@actions/exec');
async function run() {
await exec.exec('echo', ['Hello, world!']);
}
run();
Capture Output
This feature allows you to capture the output and error streams of the executed command. In this example, the 'node -v' command is executed, and its output and error streams are captured and printed to the console.
const exec = require('@actions/exec');
async function run() {
let myOutput = '';
let myError = '';
const options = {};
options.listeners = {
stdout: (data) => {
myOutput += data.toString();
},
stderr: (data) => {
myError += data.toString();
}
};
await exec.exec('node', ['-v'], options);
console.log('Output:', myOutput);
console.log('Error:', myError);
}
run();
Command with Options
This feature allows you to execute commands with additional options such as the working directory and environment variables. In this example, the 'ls -la' command is executed in a specified working directory with a custom environment variable.
const exec = require('@actions/exec');
async function run() {
const options = {
cwd: '/path/to/working/directory',
env: { MY_VAR: 'value' }
};
await exec.exec('ls', ['-la'], options);
}
run();
Other packages similar to @actions/exec
child_process
The 'child_process' module is a built-in Node.js module that provides the ability to spawn child processes. It offers similar functionalities to @actions/exec, such as executing shell commands and capturing their output. However, it is more low-level and requires more boilerplate code to achieve the same tasks.
shelljs
ShellJS is a popular npm package that provides portable Unix shell commands for Node.js. It offers a higher-level API compared to 'child_process' and includes additional utilities for file system operations. While it is not specifically designed for GitHub Actions, it can be used to achieve similar command execution functionalities.
execa
Execa is a modern npm package for executing shell commands in Node.js. It provides a promise-based API, better error handling, and more features compared to 'child_process'. Execa is a good alternative to @actions/exec for general-purpose command execution in Node.js applications.
@actions/exec
Usage
Basic
You can use this package to execute tools in a cross platform way:
const exec = require('@actions/exec');
await exec.exec('node index.js');
Args
You can also pass in arg arrays:
const exec = require('@actions/exec');
await exec.exec('node', ['index.js', 'foo=bar']);
Output/options
Capture output or specify other options:
const exec = require('@actions/exec');
let myOutput = '';
let myError = '';
const options = {};
options.listeners = {
stdout: (data: Buffer) => {
myOutput += data.toString();
},
stderr: (data: Buffer) => {
myError += data.toString();
}
};
options.cwd = './lib';
await exec.exec('node', ['index.js', 'foo=bar'], options);
Exec tools not in the PATH
You can specify the full path for tools not in the PATH:
const exec = require('@actions/exec');
await exec.exec('"/path/to/my-tool"', ['arg1']);