toolkit/packages/exec

@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']);

CommandRunner

CommandRunner is a more feature-rich alternative to exec.getExecOutput, it adds another level of abstraction to adjust behavior depending on execution results.

Example with echo command on different platforms

const commandRunner = exec.createCommandRunner()

// Set command and arguments that are platform-specific
if (IS_WINDOWS) {
  runner.setCommand(await io.which('cmd', true))
  runner.setArgs(['/c', 'echo'])
} else {
  runner.setCommand(await io.which('echo', true))
}

// Set arguments that should be added regardless of platform
runner.setArgs((...args) => [...args, 'hello', 'world'])

// Run just like exec.getExecOutput
const { stdout, stderr, exitCode } = await runner.run()

Handling outputs example:

await exec.createCommandRunner('echo', ['hello', 'world'])
  .onExecutionError('fail', 'optional fail message') // will fail action if command failed to execute
  .onStdError('log') // will log automatically generated message if command output has produced stderr
  .onExitCode('> 0', 'throw') // will throw error on non-zero exit code
  .run()

Handling options:

• onEmptyOutput('throw' | 'fail' | 'log' | handler, [, message]) - triggers on empty output
• onExecutionError('throw' | 'fail' | 'log' | handler, [, message]) - triggers when failed to execute command itself
• onStdError('throw' | 'fail' | 'log' | handler, [, message]) - triggers when command reports that it was executed with errors
• onError('throw' | 'fail' | 'log' | handler, [,message]) - triggers either when failed to execute command or when command has been executed with stderr
• onSuccess('throw' | 'fail' | 'log' | handler, [, message]) - triggers when there's no errors and exitCode equals to zero
• onSpecificError(RegExp | string | matcherFn, 'throw' | 'fail' | 'log' | handler, [, message]) - matches specific error to handle
• onOutput(RegExp | string | matcherFn, 'throw' | 'fail' | 'log' | handler, [, message]) - matches specific stdout to handle
• onExitCode(string | number, 'throw' | 'fail' | 'log' | handler, [, message]) - matches specific exitCode to handle, when exitCode is passed is string it can be prefixed with an operator, i.e: > 0, >= 1, = 31, etc.
• on(eventOrEventArray, 'throw' | 'fail' | 'log' | handler [, message] ) - matches specific event in fasion similar to other handlers, but can be set to be triggered by different events passed as array (i.e. ['execerr', 'stderr'] - any error) or by events not occuring using ! prefix (i.e. '!stdout' - empty output), allowed events:
  • 'execerr' - command failed to run
  • 'stderr' - command had run but produced stderr
  • 'stdout' - non-empty stdout
  • 'exitcode' - non-zero exit code
  • 'ok' - non-zero exit code + no stderr + no execerr