Development tools for GitHub Actions

You can create actions more quickly using some GitHub-developed tools and features.

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. GitHub Actions is unavailable for per-repository plans, which are legacy billing plans. For more information, see "GitHub's products."

In this article

Node.js toolkit for GitHub Actions

If you're developing a Node.js project, the actions toolkit provides packages that you can use in your project to speed up development. For more information, see the actions/toolkit repository.

To get started quickly, you can create a repository using the JavaScript or Docker container action template repositories. For more information see, "JavaScript action template", "Docker container action template", and "Creating a repository from a template."

Logging commands

Actions can communicate with the runner machine to set environment variables, output values used by other actions, add debug messages to the output logs, and other tasks.

Logging commands use the echo command in a specific format.

echo "::log-command parameter1={data},parameter2={data}::{command value}"

Note: Log command and parameter names are not case-sensitive.

Warning: If you are using Command Prompt, omit double quote characters (") when using logging commands.

GitHub Actions includes a variety of commands.

Set an environment variable: set-env

::set-env name={name}::{value}

Creates or updates an environment variable for any actions running next in a job. The action that creates or updates the environment variable does not have access to the new value, but all subsequent actions in a job will have access. Environment variables are case-sensitive and you can include punctuation.

Example
echo "::set-env name=action_state::yellow"

Set an output parameter: set-output

::set-output name={name}::{value}

Sets an action's output parameter. Output parameters are defined in an action's metadata file. For more information, see "Metadata syntax for GitHub Actions."

You will receive an error if you attempt to set an output value that was not declared in the action's metadata file.

Example
echo "::set-output name=action_fruit::strawberry"

Add a system path: add-path

::add-path::{path}

Prepends a directory to the system PATH variable for all subsequent actions in the current job. The currently running action cannot access the new path variable.

Example
echo "::add-path::/path/to/dir"

Set a debug message: debug

::debug::{message}

Prints a debug message to the log. You must create a secret named ACTIONS_STEP_DEBUG with the value true to see the debug messages set by this command in the log. To learn more about creating secrets and using them in a step, see "Creating and using encrypted secrets."

Example
echo "::debug file=app.js,line=1::Entered octocatAddition method"

Set a warning message: warning

::warning file={name},line={line},col={col}::{message}

Creates a warning message and prints the message to the log. You can optionally provide a filename (file), line number (line), and column (col) number where the warning occurred.

Example
echo "::warning file=app.js,line=1,col=5::Missing semicolon"

Set an error message: error

::error file={name},line={line},col={col}::{message}

Creates an error message and prints the message to the log. You can optionally provide a filename (file), line number (line), and column (col) number where the warning occurred.

Example
echo "::error file=app.js,line=10,col=15::Something went wrong"

Mask a value in log: add-mask

::add-mask::{value}

Masking a value prevents a string or variable from being printed in the log. Each masked word separated by whitespace is replaced with the * character. You can use an environment variable or string for the mask's value.

Example masking a string

When you print "Mona The Octocat" in the log, you'll see "***".

echo "::add-mask::Mona The Octocat"
Example masking an environment variable

When you print the variable MY_NAME or the value "Mona The Octocat" in the log, you'll see "***" instead of "Mona The Octocat".

MY_NAME="Mona The Octocat"
echo "::add-mask::$MY_NAME"

Stop and start log commands: stop-commands

::stop-commands::{endtoken}

Stops processing any logging commands. This special command allows you to log anything without accidentally running a log command. For example, you could stop logging to output an entire script that has comments.

Example stopping log commands
echo "::stop-commands::pause-logging"

To start log commands, pass the token that you used to stop logging.

::{endtoken}::

Example starting log commands
echo "::pause-logging::"

Setting an action's status using exit codes

GitHub uses the exit code to set the GitHub Action's check run status, which can be success or failure.

Exit status Check run status Description
0 success The action completed successfully and other tasks that depends on it can begin.
Nonzero value failure Any other exit code indicates the action failed. When an action fails, all concurrent actions are canceled and future actions are skipped. The check run and check suite both get a failure status.

Setting a failure exit code in a JavaScript action

If you are creating a JavaScript action, you can use the actions toolkit @actions/core package to log a message and set a failure exit code. For example:

try {
  // something
} catch (error) {
  core.setFailed(error.message);
}

For more information, see "Creating a JavaScript action."

Setting a failure exit code in a Docker container action

If you are creating a Docker container action, you can set a failure exit code in your entrypoint.sh script. For example:

if <condition> ; then
  echo "Game over!"
  exit 1
fi

For more information, see "Creating a Docker container action."

Ask a human

Can't find what you're looking for?

Contact us