Movatterモバイル変換


[0]ホーム

URL:


Skip to main content
GitHub Docs

Workflow commands for GitHub Actions

You can use workflow commands when running shell commands in a workflow or in an action's code.

Tool navigation

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 theecho command in a specific format, while others are invoked by writing to a file. For more information, seeEnvironment files.

Example of a workflow command

Bash
echo"::workflow-command parameter1={data},parameter2={data}::{command value}"
PowerShell
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

Theactions/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 overstdout.

For example, instead of using code to create an error annotation, as below:

JavaScript
core.error('Missing semicolon', {file:'app.js',startLine:1})

Example: Creating an annotation for an error

You can use theerror command in your workflow to create the same error annotation:

YAML
-name:Createannotationforbuilderrorrun:echo"::error file=app.js,line=1::Missing semicolon"
YAML
-name:Createannotationforbuilderrorrun:Write-Output"::error file=app.js,line=1::Missing semicolon"

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

Toolkit functionEquivalent workflow command
core.addPathAccessible using environment fileGITHUB_PATH
core.debugdebug
core.noticenotice
core.errorerror
core.endGroupendgroup
core.exportVariableAccessible using environment fileGITHUB_ENV
core.getInputAccessible using environment variableINPUT_{NAME}
core.getStateAccessible using environment variableSTATE_{NAME}
core.isDebugAccessible using environment variableRUNNER_DEBUG
core.summaryAccessible using environment fileGITHUB_STEP_SUMMARY
core.saveStateAccessible using environment fileGITHUB_STATE
core.setCommandEchoecho
core.setFailedUsed as a shortcut for::error andexit 1
core.setOutputAccessible using environment fileGITHUB_OUTPUT
core.setSecretadd-mask
core.startGroupgroup
core.warningwarning

Setting a debug message

Prints a debug message to the log. You must create a secret namedACTIONS_STEP_DEBUG with the valuetrue to see the debug messages set by this command in the log. For more information, seeEnabling debug logging.

Text
::debug::{message}

Example: Setting a debug message

Bash
echo"::debug::Set the Octocat variable"
PowerShell
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.

Text
::notice file={name},line={line},endLine={endLine},title={title}::{message}
ParameterValueRequiredDefault
titleCustom titleNoNone
fileFilenameNo.github
colColumn number, starting at 1NoNone
endColumnEnd column numberNoNone
lineLine number, starting at 1No1
endLineEnd line numberNo1

Example: Setting a notice message

Bash
echo"::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
PowerShell
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.

Text
::warning file={name},line={line},endLine={endLine},title={title}::{message}
ParameterValueRequiredDefault
titleCustom titleNoNone
fileFilenameNo.github
colColumn number, starting at 1NoNone
endColumnEnd column numberNoNone
lineLine number, starting at 1No1
endLineEnd line numberNo1

Example: Setting a warning message

Bash
echo"::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
PowerShell
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.

Text
::error file={name},line={line},endLine={endLine},title={title}::{message}
ParameterValueRequiredDefault
titleCustom titleNoNone
fileFilenameNo.github
colColumn number, starting at 1NoNone
endColumnEnd column numberNoNone
lineLine number, starting at 1No1
endLineEnd line numberNo1

Example: Setting an error message

Bash
echo"::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
PowerShell
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 thegroup command and specify atitle. Anything you print to the log between thegroup andendgroup commands is nested inside an expandable entry in the log.

Text
::group::{title}::endgroup::

Example: Grouping log lines

YAML
jobs:bash-example:runs-on:ubuntu-lateststeps:-name:Groupofloglinesrun:|            echo "::group::My title"            echo "Inside group"            echo "::endgroup::"
YAML
jobs:powershell-example:runs-on:windows-lateststeps:-name:Groupofloglinesrun:|            Write-Output "::group::My title"            Write-Output "Inside group"            Write-Output "::endgroup::"

Screenshot of the log for the workflow step. The second line, "My title", is an expanded group. The next line, "Inside group", is indented below.

Masking a value in a log

Text
::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'svalue. 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"***".

Bash
echo"::add-mask::Mona The Octocat"
PowerShell
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 variableMY_NAME or the value"Mona The Octocat" in the log, you'll see"***" instead of"Mona The Octocat".

YAML
jobs:bash-example:runs-on:ubuntu-latestenv:MY_NAME:"Mona The Octocat"steps:-name:bash-versionrun:echo"::add-mask::$MY_NAME"
YAML
jobs:powershell-example:runs-on:windows-latestenv:MY_NAME:"Mona The Octocat"steps:-name:powershell-versionrun: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:

  1. Generate the secret (without outputting it).
  2. Mask it withadd-mask.
  3. UseGITHUB_OUTPUT to make the secret available to other steps within the job.
YAML
on:pushjobs:generate-a-secret-output:runs-on:ubuntu-lateststeps:-id:sets-a-secretname:Generate,mask,andoutputasecretrun:|          the_secret=$((RANDOM))          echo "::add-mask::$the_secret"          echo "secret-number=$the_secret" >> "$GITHUB_OUTPUT"-name:Usethatsecretoutput(protectedbyamask)run:|          echo "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"
YAML
on:pushjobs:generate-a-secret-output:runs-on:ubuntu-lateststeps:-id:sets-a-secretname:Generate,mask,andoutputasecretshell:pwshrun:|          Set-Variable -Name TheSecret -Value (Get-Random)          Write-Output "::add-mask::$TheSecret"          "secret-number=$TheSecret" >> $env:GITHUB_OUTPUT-name:Usethatsecretoutput(protectedbyamask)shell:pwshrun:|          Write-Output "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"

Example: Masking and passing a secret between jobs or workflows

If you want to pass a masked secret between jobs or workflows, you should store the secret in a store and then retrieve it in the subsequent job or workflow.

Setup

  1. Set up a secret store to store the secret that you will generate during your workflow. For example, Vault.
  2. Generate a key for reading and writing to that secret store. Store the key as a repository secret. In the following example workflow, the secret name isSECRET_STORE_CREDENTIALS. For more information, seeUsing secrets in GitHub Actions.

Workflow

Note

This workflow uses an imaginary secret store,secret-store, which has imaginary commandsstore-secret andretrieve-secret.some/secret-store@ 27b31702a0e7fc50959f5ad993c78deac1bdfc29 is an imaginary action that installs thesecret-store application and configures it to connect to aninstance withcredentials.

YAML
on:pushjobs:secret-generator:runs-on:ubuntu-latestoutputs:handle:${{steps.generate-secret.outputs.handle}}steps:-uses:some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29with:credentials:${{secrets.SECRET_STORE_CREDENTIALS}}instance:${{secrets.SECRET_STORE_INSTANCE}}-name:generatesecretid:generate-secretshell:bashrun:|        GENERATED_SECRET=$((RANDOM))        echo "::add-mask::$GENERATED_SECRET"        SECRET_HANDLE=$(secret-store store-secret "$GENERATED_SECRET")        echo "handle=$SECRET_HANDLE" >> "$GITHUB_OUTPUT"secret-consumer:runs-on:macos-latestneeds:secret-generatorsteps:-uses:some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29with:credentials:${{secrets.SECRET_STORE_CREDENTIALS}}instance:${{secrets.SECRET_STORE_INSTANCE}}-name:usesecretshell:bashrun:|        SECRET_HANDLE="${{ needs.secret-generator.outputs.handle }}"        RETRIEVED_SECRET=$(secret-store retrieve-secret "$SECRET_HANDLE")        echo "::add-mask::$RETRIEVED_SECRET"        echo "We retrieved our masked secret: $RETRIEVED_SECRET"
YAML
on:pushjobs:secret-generator:runs-on:ubuntu-lateststeps:-uses:some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29with:credentials:${{secrets.SECRET_STORE_CREDENTIALS}}instance:${{secrets.SECRET_STORE_INSTANCE}}-name:generatesecretshell:pwshrun:|        Set-Variable -Name Generated_Secret -Value (Get-Random)        Write-Output "::add-mask::$Generated_Secret"        Set-Variable -Name Secret_Handle -Value (Store-Secret "$Generated_Secret")        "handle=$Secret_Handle" >> $env:GITHUB_OUTPUTsecret-consumer:runs-on:macos-latestneeds:secret-generatorsteps:-uses:some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29with:credentials:${{secrets.SECRET_STORE_CREDENTIALS}}instance:${{secrets.SECRET_STORE_INSTANCE}}-name:usesecretshell:pwshrun:|        Set-Variable -Name Secret_Handle -Value "${{ needs.secret-generator.outputs.handle }}"        Set-Variable -Name Retrieved_Secret -Value (Retrieve-Secret "$Secret_Handle")        echo "::add-mask::$Retrieved_Secret"        echo "We retrieved our masked secret: $Retrieved_Secret"

Stopping and starting workflow commands

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

Text
::stop-commands::{endtoken}

To stop the processing of workflow commands, pass a unique token tostop-commands. To resume processing workflow commands, pass the same token that you used to stop workflow commands.

Warning

Make sure the token you're using is randomly generated and unique for each run.

Text
::{endtoken}::

Example: Stopping and starting workflow commands

YAML
jobs:workflow-command-job:runs-on:ubuntu-lateststeps:-name:Disableworkflowcommandsrun:|          echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'          stopMarker=$(uuidgen)          echo "::stop-commands::$stopMarker"          echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'          echo "::$stopMarker::"          echo '::warning:: This is a warning again, because stop-commands has been turned off.'
YAML
jobs:workflow-command-job:runs-on:windows-lateststeps:-name:Disableworkflowcommandsrun:|          Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'          $stopMarker = New-Guid          Write-Output "::stop-commands::$stopMarker"          Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'          Write-Output "::$stopMarker::"          Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'

Sending values to the pre and post actions

You can create environment variables for sharing with your workflow'spre: orpost: actions by writing to the file located atGITHUB_STATE. For example, you can create a file with thepre: action, pass the file location to themain: action, and then use thepost: action to delete the file. Alternatively, you could create a file with themain: action, pass the file location to thepost: action, and also use thepost: action to delete the file.

If you have multiplepre: orpost: actions, you can only access the saved value in the action where it was written toGITHUB_STATE. For more information on thepost: action, seeMetadata syntax reference.

TheGITHUB_STATE file is only available within an action. The saved value is stored as an environment value with theSTATE_ prefix.

This example uses JavaScript to write to theGITHUB_STATE file. The resulting environment variable is namedSTATE_processID with the value of12345:

JavaScript
import *as fsfrom'fs'import *as osfrom'os'fs.appendFileSync(process.env.GITHUB_STATE,`processID=12345${os.EOL}`, {encoding:'utf8'})

TheSTATE_processID variable is then exclusively available to the cleanup script running under themain action. This example runs inmain and uses JavaScript to display the value assigned to theSTATE_processID environment variable:

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

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 can be accessed and edited using GitHub's default environment variables. SeeVariables reference. You will need to use 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.To use environment variables in a GitHub Action, you create or modify.env files using specific GitHub Actions commands.

Here's how:

YAML
name:ExampleWorkflowforEnvironmentFileson:pushjobs:set_and_use_env_vars:runs-on:ubuntu-lateststeps:-name:Setenvironmentvariablerun:echo"MY_ENV_VAR=myValue">>$GITHUB_ENV-name:Useenvironmentvariablerun:|          echo "The value of MY_ENV_VAR is $MY_ENV_VAR"

Another example would be to use it to store metadata like build timestamps, commit SHAs, or artifact names:

YAML
steps:-name:Storebuildtimestamprun:echo"BUILD_TIME=$(date +'%T')">>$GITHUB_ENV-name:Deployusingstoredtimestamprun:echo"Deploying at $BUILD_TIME"

Note

PowerShell versions 5.1 and below (shell: powershell) do not use UTF-8 by default, so you must specify the UTF-8 encoding. For example:

YAML
jobs:legacy-powershell-example:runs-on:windows-lateststeps:-shell:powershellrun:|          "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

PowerShell Core versions 6 and higher (shell: pwsh) use UTF-8 by default. For example:

YAML
jobs:powershell-core-example:runs-on:windows-lateststeps:-shell:pwshrun:|          "mypath" >> $env:GITHUB_PATH

Setting an environment variable

Note

To avoid issues, it's good practice to treat environment variables as case sensitive, irrespective of the behavior of the operating system and shell you are using.

Bash
echo"{environment_variable_name}={value}" >>"$GITHUB_ENV"
  • Using PowerShell version 6 and higher:

    PowerShell
    "{environment_variable_name}={value}" >>$env:GITHUB_ENV
  • Using PowerShell version 5.1 and below:

    PowerShell
    "{environment_variable_name}={value}" |Out-File-FilePath$env:GITHUB_ENV-Encoding utf8-Append

You can make an environment variable available to any subsequent steps in a workflow job by defining or updating the environment variable and writing this to theGITHUB_ENV environment file. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access.

You can't overwrite the value of the default environment variables namedGITHUB_* andRUNNER_*. Currently you can overwrite the value of theCI variable. However, it's not guaranteed that this will always be possible. For more information about the default environment variables, seeStore information in variables.

Note

Due to security restrictions,GITHUB_ENV cannot be used to set theNODE_OPTIONS environment variable.

Example of writing an environment variable toGITHUB_ENV

YAML
steps:-name:Setthevalueid:step_onerun:|      echo "action_state=yellow" >> "$GITHUB_ENV"-name:Usethevalueid:step_tworun:|      printf '%s\n' "$action_state" # This will output 'yellow'
YAML
steps:-name:Setthevalueid:step_onerun:|      "action_state=yellow" >> $env:GITHUB_ENV-name:Usethevalueid:step_tworun:|      Write-Output "$env:action_state" # This will output 'yellow'

Multiline strings

For multiline strings, you may use a delimiter with the following syntax.

Text
{name}<<{delimiter}{value}{delimiter}

Warning

Make sure the delimiter you're using won't occur on a line of its own within the value. If the value is completely arbitrary then you shouldn't use this format. Write the value to a file instead.

Example of a multiline string

This example usesEOF as the delimiter, and sets theJSON_RESPONSE environment variable to the value of thecurl response.

YAML
steps:-name:Setthevalueinbashid:step_onerun:|      {        echo 'JSON_RESPONSE<<EOF'        curl https://example.com        echo EOF      } >> "$GITHUB_ENV"
YAML
steps:-name:Setthevalueinpwshid:step_onerun:|      $EOF = (New-Guid).Guid      "JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV      "$EOF" >> $env:GITHUB_ENVshell:pwsh

Setting an output parameter

Sets a step's output parameter. Note that the step will need anid to be defined to later retrieve the output value. You can set multi-line output values with the same technique used in theMultiline strings section to define multi-line environment variables.

Bash
echo"{name}={value}" >>"$GITHUB_OUTPUT"
PowerShell
"{name}=value" >>$env:GITHUB_OUTPUT

Example of setting an output parameter

This example demonstrates how to set theSELECTED_COLOR output parameter and later retrieve it:

YAML
-name:Setcolorid:color-selectorrun:echo"SELECTED_COLOR=green">>"$GITHUB_OUTPUT"-name:Getcolorenv:SELECTED_COLOR:${{steps.color-selector.outputs.SELECTED_COLOR}}run:echo"The selected color is $SELECTED_COLOR"

This example demonstrates how to set theSELECTED_COLOR output parameter and later retrieve it:

YAML
-name:Setcolorid:color-selectorrun:|            "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT-name:Getcolorenv:SELECTED_COLOR:${{steps.color-selector.outputs.SELECTED_COLOR}}run:Write-Output"The selected color is $env:SELECTED_COLOR"

Adding a job summary

Bash
echo"{markdown content}" >>$GITHUB_STEP_SUMMARY
PowerShell
"{markdown content}" >>$env:GITHUB_STEP_SUMMARY

You can set some custom Markdown for each job so that it will be displayed on the summary page of a workflow run. You can use job summaries to display and group unique content, such as test result summaries, so that someone viewing the result of a workflow run doesn't need to go into the logs to see important information related to the run, such as failures.

Job summaries supportGitHub flavored Markdown, and you can add your Markdown content for a step to theGITHUB_STEP_SUMMARY environment file.GITHUB_STEP_SUMMARY is unique for each step in a job. For more information about the per-step file thatGITHUB_STEP_SUMMARY references, seeEnvironment files.

When a job finishes, the summaries for all steps in a job are grouped together into a single job summary and are shown on the workflow run summary page. If multiple jobs generate summaries, the job summaries are ordered by job completion time.

Example of adding a job summary

Bash
echo"### Hello world! :rocket:" >>$GITHUB_STEP_SUMMARY
PowerShell
"### Hello world! :rocket:" >>$env:GITHUB_STEP_SUMMARY

Screenshot of the summary page of a workflow run. Under "example summary" is "Hello world!" and a rocket emoji.

Multiline Markdown content

For multiline Markdown content, you can use>> to continuously append content for the current step. With every append operation, a newline character is automatically added.

Example of multiline Markdown content

-name:GeneratelistusingMarkdownrun:|    echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY    echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line    echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY    echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY    echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY
-name:GeneratelistusingMarkdownrun:|    "This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY    "" >> $env:GITHUB_STEP_SUMMARY # this is a blank line    "- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY    "- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY    "- How about a third one?" >> $env:GITHUB_STEP_SUMMARY

Overwriting job summaries

To clear all content for the current step, you can use> to overwrite any previously added content in Bash, or remove-Append in PowerShell

Example of overwriting job summaries

-name:OverwriteMarkdownrun:|    echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY    echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY
-name:OverwriteMarkdownrun:|    "Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY    "There was an error, we need to clear the previous Markdown with some new content." >> $env:GITHUB_STEP_SUMMARY

Removing job summaries

To completely remove a summary for the current step, the file thatGITHUB_STEP_SUMMARY references can be deleted.

Example of removing job summaries

-name:Deleteallsummarycontentrun:|    echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY    rm $GITHUB_STEP_SUMMARY
-name:Deleteallsummarycontentrun:|    "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY    Remove-Item $env:GITHUB_STEP_SUMMARY

After a step has completed, job summaries are uploaded and subsequent steps cannot modify previously uploaded Markdown content. Summaries automatically mask any secrets that might have been added accidentally. If a job summary contains sensitive information that must be deleted, you can delete the entire workflow run to remove all its job summaries. For more information seeDeleting a workflow run.

Step isolation and limits

Job summaries are isolated between steps and each step is restricted to a maximum size of 1MiB. Isolation is enforced between steps so that potentially malformed Markdown from a single step cannot break Markdown rendering for subsequent steps. If more than 1MiB of content is added for a step, then the upload for the step will fail and an error annotation will be created. Upload failures for job summaries do not affect the overall status of a step or a job. A maximum of 20 job summaries from steps are displayed per job.

Adding a system path

Prepends a directory to the systemPATH variable and automatically makes it available to all subsequent actions in the current job; the currently running action cannot access the updated path variable. To see the currently defined paths for your job, you can useecho "$PATH" in a step or an action.

Example of adding a system path

This example demonstrates how to add the user$HOME/.local/bin directory toPATH:

Bash
echo"$HOME/.local/bin" >>"$GITHUB_PATH"

This example demonstrates how to add the user$env:HOMEPATH/.local/bin directory toPATH:

PowerShell
"$env:HOMEPATH/.local/bin" |Out-File-FilePath"$env:GITHUB_PATH"-Append

[8]ページ先頭

©2009-2025 Movatter.jp