Workflow commands for GitHub Actions

About workflow 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.

Workflow commands use the echo command in a specific format.

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

Using workflow commands to access toolkit functions

The actions/toolkit includes a number of functions that can be executed as workflow commands. Use the :: syntax to run the workflow commands within your YAML file; these commands are then sent to the runner over stdout. For example, instead of using code to set an environment variable, as below:

core.exportVariable('SELECTED_COLOR', 'green');

You can use the set-env command in your workflow to set the same value:

      - name: Set selected color
        run: echo '::set-env name=SELECTED_COLOR::green'
      - name: Get color
        run: echo 'The selected color is' $SELECTED_COLOR

The following table shows which toolkit functions are available within a workflow:

Setting an environment variable

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

Cria ou atualiza uma variável de ambiente para quaisquer ações a serem executadas em seguida no trabalho. A ação que cria ou atualiza a variável de ambiente não tem acesso a um valor novo, mas todas as ações subsequentes em um trabalho terão. As variáveis de ambiente diferenciam maiúsculas de minúsculas e podem ter pontuação.

Exemplo

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

Setting an output parameter

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

Configura um parâmetro de saída da ação.

Optionally, you can also declare output parameters in an action's metadata file. Para obter mais informações, consulte "Sintaxe de metadados para o GitHub Actions".

Exemplo

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

Adding a system path

::add-path::{path}

Agrega um diretório à variável de sistema PATH para todas as ações subsequentes no trabalho atual. A ação que está em execução não pode acessar a nova variável de caminho.

Exemplo

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

Setting a debug message

::debug::{message}

Imprime uma mensagem de erro no log. Você deve criar um segredo nomeado ACTIONS_STEP_DEBUG com o valor true para ver as mensagens de erro configuradas por esse comando no 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"

Setting a warning message

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

Cria uma mensagem de aviso e a imprime no log. Como opção, você pode fornecer um nome de arquivo (file), número de linha (line) e número de coluna (col) onde o aviso ocorreu.

Example

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

Setting an error message

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

Cria uma mensagem de erro e a imprime no log. Como opção, você pode fornecer um nome de arquivo (file), número de linha (line) e número de coluna (col) onde o aviso ocorreu.

Example

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

Masking a value in log

::add-mask::{value}

Mascarar um valor evita que uma string ou variável seja impressa no log. Cada palavra mascarada separada por espaço em branco é substituída pelo caractere *. Você pode usar uma variável de ambiente ou string para o value da máscara.

Exemplo de máscara de string

Quando você imprime "Mona The Octocat" no log, você verá "***".

echo "::add-mask::Mona The Octocat"

Exemplo de máscara de uma variável de ambiente

Ao imprimir a variável MY_NAME ou o valor "Mona The Octocat" no log, você verá "***" em vez de "Mona The Octocat".

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

Stopping and starting workflow commands

::stop-commands::{endtoken}

Stops processing any workflow commands. This special command allows you to log anything without accidentally running a workflow command. Por exemplo, é possível parar o log para gerar um script inteiro que tenha comentários.

Example stopping workflow commands

echo "::stop-commands::pause-logging"

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

::{endtoken}::

Example starting workflow commands

echo "::pause-logging::"

Sending values to the pre and post actions

You can use the save-state command to create environment variables for sharing with your workflow's pre: or post: actions. For example, you can create a file with the pre: action, pass the file location to the main: action, and then use the post: action to delete the file. Alternatively, you could create a file with the main: action, pass the file location to the post: action, and also use the post: action to delete the file.

If you have multiple pre: or post: actions, you can only access the saved value in the action where save-state was used. For more information on the post: action, see "Metadata syntax for GitHub Actions."

The save-state command can only be run within an action, and is not available to YAML files. The saved value is stored as an environment value with the STATE_ prefix.

This example uses JavaScript to run the save-state command. The resulting environment variable is named STATE_processID with the value of 12345:

console.log('::save-state name=processID::12345')

The STATE_processID variable is then exclusively available to the cleanup script running under the main action. This example runs in main and uses JavaScript to display the value assigned to the STATE_processID environment variable:

console.log("The running PID from the main action is: " +  process.env.STATE_processID);