toolkit/docs/commands.md

:: Commands

The core toolkit package offers a number of convenience functions for setting results, logging, registering secrets and exporting variables across actions. Sometimes, however, its useful to be able to do these things in a script or other tool.

To allow this, we provide a special :: syntax which, if logged to stdout on a new line, will allow the runner to perform special behavior on your commands. The following commands are all supported:

Set outputs

To set an output for the step, use ::set-output:

echo "::set-output name=FOO::BAR"

Running steps.[step-id].outputs.FOO in your Yaml will now give you BAR

steps:
  - name: Set the value
    id: step_one
    run: echo "::set-output name=FOO::BAR"
  - name: Use it
    run: echo ${{ steps.step_one.outputs.FOO }}

This is wrapped by the core setOutput method:

export function setOutput(name: string, value: string): void {}

Register a secret

If a script or action does work to create a secret at runtime, it can be registered with the runner to be masked in logs.

To mask a value in the logs, use ::add-mask:

echo "::add-mask::mysecretvalue"

This is wrapped by the core setSecret method

function setSecret(secret: string): void {}

Now, future logs containing BAR will be masked. E.g. running echo "Hello FOO BAR World" will now print Hello FOO **** World.

WARNING The add-mask and setSecret commands only support single line secrets. To register a multiline secrets you must register each line individually otherwise it will not be masked.

WARNING Do not mask short values if you can avoid it, it could render your output unreadable (and future steps' output as well). For example, if you mask the letter l, running echo "Hello FOO BAR World" will now print He*********o FOO BAR Wor****d

Group and Ungroup Log Lines

Emitting a group with a title will instruct the logs to create a collapsible region up to the next endgroup command.

echo "::group::my title"   
echo "::endgroup::"

This is wrapped by the core methods:

function startGroup(name: string): void {}
function endGroup(): void {}

Problem Matchers

Problems matchers can be used to scan a build's output to automatically surface lines to the user that matches the provided pattern. A file path to a .json Problem Matcher must be provided. See Problem Matchers for more information on how to define a Problem Matcher.

echo "::add-matcher::eslint-compact-problem-matcher.json"   
echo "::remove-matcher owner=eslint-compact::"

add-matcher takes a path to a Problem Matcher file remove-matcher removes a Problem Matcher by owner

Save State

Save a state to an environmental variable that can later be used in the main or post action.

echo "::save-state name=FOO::foovalue"

Because save-state prepends the string STATE_ to the name, the environment variable STATE_FOO will be available to use in the post or main action. See Sending Values to the pre and post actions for more information.

Log Level

There are several commands to emit different levels of log output:

log level	example usage
debug	echo "::debug::My debug message"
notice	echo "::notice::My notice message"
warning	echo "::warning::My warning message"
error	echo "::error::My error message"

Additional syntax options are described at the workflow command documentation.

Command Echoing

By default, the echoing of commands to stdout only occurs if Step Debugging is enabled

You can enable or disable this for the current step by using the echo command.

echo "::echo::on"

You can also disable echoing.

echo "::echo::off"

This is wrapped by the core method:

function setCommandEcho(enabled: boolean): void {}

The add-mask, debug, warning and error commands do not support echoing.

Command Prompt

CMD processes the " character differently from other shells when echoing. In CMD, the above snippets should have the " characters removed in order to correctly process. For example, the set output command would be:

echo ::set-output name=FOO::BAR

Environment files

During the execution of a workflow, the runner generates temporary files that can be used to perform certain actions. The path to these files are exposed via environment variables. You will need to use the utf-8 encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines.

Set an environment variable

To set an environment variable for future out of process steps, write to the file located at GITHUB_ENV or use the equivalent actions/core function

echo "FOO=BAR" >> $GITHUB_ENV

Running $FOO in a future step will now return BAR

For multiline strings, you may use a heredoc style syntax with your choice of delimeter. In the below example, we use EOF.

steps:
  - name: Set the value
    id: step_one
    run: |
        echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
        curl https://httpbin.org/json >> $GITHUB_ENV
        echo 'EOF' >> $GITHUB_ENV

This would set the value of the JSON_RESPONSE env variable to the value of the curl response.

The expected syntax for the heredoc style is:

{VARIABLE_NAME}<<{DELIMETER}
{VARIABLE_VALUE}
{DELIMETER}

This is wrapped by the core exportVariable method which sets for future steps but also updates the variable for this step.

export function exportVariable(name: string, val: string): void {}

PATH Manipulation

To prepend a string to PATH write to the file located at GITHUB_PATH or use the equivalent actions/core function

echo "/Users/test/.nvm/versions/node/v12.18.3/bin" >> $GITHUB_PATH

Running $PATH in a future step will now return /Users/test/.nvm/versions/node/v12.18.3/bin:{Previous Path};

This is wrapped by the core addPath method:

export function addPath(inputPath: string): void {}

Powershell

Powershell does not use UTF8 by default. You will want to make sure you write in the correct encoding. For example, to set the path:

steps:
  - run: echo "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append