Workflow commands for GitHub Actions - GitHub Docs
Skip to main content Skip to content Collapse sidebar Expand sidebar Workflow commands for GitHub Actions You can use workflow commands when running shell commands in a workflow or in an action's code. In this article 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. Most workflow commands use the echo command in a specific format, while others are invoked by writing to a file.
For more information, see Environment files . Example of a workflow command echo "::workflow-command parameter1={data},parameter2={data}::{command value}" Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}" Note Workflow command and parameter names are case insensitive. Warning If you are using Command Prompt, omit double quote characters ( " ) when using workflow commands. 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 create an error annotation, as below: core. error ( 'Missing semicolon' , { file : 'app.js' , startLine : 1 }) Example: Creating an annotation for an error You can use the error command in your workflow to create the same error annotation: - name: Create annotation for build error run: echo "::error file=app.js,line=1::Missing semicolon" - name: Create annotation for build error run: Write-Output "::error file=app.js,line=1::Missing semicolon" The following table shows which toolkit functions are available within a workflow: Toolkit function Equivalent workflow command core.addPath Accessible using environment file GITHUB_PATH core.debug debug core.notice notice core.error error core.endGroup endgroup core.export Variable Accessible using environment file GITHUB_ENV core.getInput Accessible using environment variable INPUT_{NAME} core.getState Accessible using environment variable STATE_{NAME} core.isDebug Accessible using environment variable RUNNER_DEBUG core.summary Accessible using environment file GITHUB_STEP_SUMMARY core.saveState Accessible using environment file GITHUB_STATE core.set Command Echo echo core.setFailed Used as a shortcut for ::error and exit 1 core.setOutput Accessible using environment file GITHUB_OUTPUT core.setSecret add-mask core.startGroup group core.warning warning Setting a 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. For more information, see Enabling debug logging . ::debug::{message} Example: Setting a debug message echo "::debug::Set the Octocat variable" Write-Output "::debug::Set the Octocat variable" Setting a notice message Creates a notice message and prints the message to the log. This message will create an annotation, which can associate the message with a particular file in your repository.
Optionally, your message can specify a position within the file. ::notice file={name},line={line},endLine={endLine},title={title}::{message} Parameter Value Required Default title Custom title No None file Filename No .github col Column number, starting at 1 No None endColumn End column number No None line Line number, starting at 1 No 1 endLine End line number No 1 Example: Setting a notice message echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon" Write-Output "::notice file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" Setting a warning message Creates a warning message and prints the message to the log.
This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file. ::warning file={name},line={line},endLine={endLine},title={title}::{message} Parameter Value Required Default title Custom title No None file Filename No .github col Column number, starting at 1 No None endColumn End column number No None line Line number, starting at 1 No 1 endLine End line number No 1 Example: Setting a warning message echo "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" Write-Output "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" Setting an error message Creates an error message and prints the message to the log.
This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file. ::error file={name},line={line},endLine={endLine},title={title}::{message} Parameter Value Required Default title Custom title No None file Filename No .github col Column number, starting at 1 No None endColumn End column number No None line Line number, starting at 1 No 1 endLine End line number No 1 Example: Setting an error message echo "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" Write-Output "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" Grouping log lines Creates an expandable group in the log.
To create a group, use the group command and specify a title . Anything you print to the log between the group and endgroup commands is nested inside an expandable entry in the log. ::group::{title} ::endgroup:: Example: Grouping log lines jobs: bash-example: runs-on: ubuntu-latest steps: - name: Group of log lines run: | echo "::group::My title" echo "Inside group" echo "::endgroup::" jobs: powershell-example: runs-on: windows-latest steps: - name: Group of log lines run: | Write-Output "::group::My title" Write-Output "Inside group" Write-Output "::endgroup::" Masking a value in a log ::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 . This must be done once per value per job. When you mask a value, it is treated as a secret and will be redacted on the runner. For example, after you mask a value, you won't be able to set that value as an output. Example: Masking a string When you print "Mona The Octocat" in the log, you'll see "***" . echo "::add-mask::Mona The Octocat" Write-Output "::add-mask::Mona The Octocat" Warning Make sure you register the secret with 'add-mask' before outputting it in the build logs or using it in any other workflow commands.
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" . jobs: bash-example: runs-on: ubuntu-latest env: MY_NAME: "Mona The Octocat" steps: - name: bash-version run: echo "::add-mask::$MY_NAME" jobs: powershell-example: runs-on: windows-latest env: MY_NAME: "Mona The Octocat" steps: - name: powershell-version run: Write-Output "::add-mask::$env:MY_NAME" Example: Masking a generated output within a single job If you do not need to pass your secret from one job to another job, you can: Generate the secret (without outputting it).
Mask it with add-mask . Use GITHUB_OUTPUT to make the secret available to other steps within the job. on: push jobs: generate-a-secret-output: runs-on: ubuntu-latest steps: - id: sets-a-secret name: Generate, mask, and output a secret run: | the_secret=$((RANDOM)) echo "::add-mask::$the_secret" echo "secret-number=$the_secret" >> "$GITHUB_OUTPUT" - name: Use that secret output (protected by a mask) run: | echo "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}" on: push jobs: generate-a-secret-output: runs-on: ubuntu-latest steps: - id: sets-a-secret name: Generate, mask, and output a secret shell: pwsh run: |
The rest of this page is on the live site.