GitHub Actions 的工作流程命令

您可以在工作流程或操作代码中运行 shell 命令时使用工作流程命令。

关于工作流程命令

操作可以与运行器机器进行通信,以设置环境变量,其他操作使用的输出值,将调试消息添加到输出日志和其他任务。

大多数工作流程命令使用特定格式的 echo 命令,而其他工作流程则通过写入文件被调用。 更多信息请参阅“环境文件”。

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

注意:工作流程命令和参数名称不区分大小写。

警告:如果您使用命令提示符,则使用工作流程命令时忽略双引号字符 (")。

使用工作流程命令访问工具包函数

actions/toolkit 包括一些可以作为工作流程命令执行的功能。 使用 :: 语法来运行您的 YAML 文件中的工作流程命令;然后,通过 stdout 将这些命令发送给运行器。 例如,不使用代码来设置环境变量,如下所示:

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

您可以在工作流程中使用 set-output 命令来设置相同的值:

      - name: Set selected color
        run: echo '::set-output name=SELECTED_COLOR::green'
        id: random-color-generator
      - name: Get color
        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

下表显示了在工作流程中可用的工具包功能:

工具包函数等效工作流程命令
core.addPathAccessible using environment file GITHUB_PATH
core.debugdebug
core.noticenotice

| core.error | error | | core.endGroup | endgroup | | core.exportVariable | Accessible using environment file GITHUB_ENV | | core.getInput | 可使用环境变量 INPUT_{NAME} 访问 | | core.getState | 可使用环境变量 STATE_{NAME} 访问 | | core.isDebug | 可使用环境变量 RUNNER_DEBUG 访问 | | core.saveState | save-state | | core.setCommandEcho | echo | | core.setFailed | 用作 ::errorexit 1 的快捷方式 | | core.setOutput | set-output | | core.setSecret | add-mask | | core.startGroup | | | core.warning | 警告 |

设置输出参数

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

设置操作的输出参数。

(可选)您也可以在操作的元数据文件中声明输出参数。 更多信息请参阅“GitHub Actions 的元数据语法”。

示例

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

设置调试消息

::debug::{message}

将调试消息打印到日志。 您可以创建名为 ACTIONS_STEP_DEBUG、值为 true 的密码,才能在日志中查看通过此命令设置的调试消息。 更多信息请参阅“启用调试日志记录”。

示例

echo "::debug::Set the Octocat variable"

设置通知消息

::notice file={name},line={line},endLine={endLine},title={title}::{message}

创建通知消息并将该消息打印到日志。 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.

| Parameter | Value | | :- | :- | | title | Custom title | | file | Filename | | col | Column number, starting at 1 | | endColumn | End column number | | line | Line number, starting at 1 | | endLine | End line number |

示例

echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

设置警告消息

::warning file={name},line={line},endLine={endLine},title={title}::{message}

创建警告消息并将该消息打印到日志。 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.

| Parameter | Value | | :- | :- | | title | Custom title | | file | Filename | | col | Column number, starting at 1 | | endColumn | End column number | | line | Line number, starting at 1 | | endLine | End line number |

示例

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

设置错误消息

::error file={name},line={line},endLine={endLine},title={title}::{message}

创建错误消息并将该消息打印到日志。 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.

| Parameter | Value | | :- | :- | | title | Custom title | | file | Filename | | col | Column number, starting at 1 | | endColumn | End column number | | line | Line number, starting at 1 | | endLine | End line number |

示例

echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

对日志行分组

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

在日志中创建一个可扩展的组。 要创建组,请使用 group 命令并指定 title。 打印到 groupendgroup 命令之间日志的任何内容都会嵌套在日志中可扩展的条目内。

示例

echo "::group::My title"
echo "Inside group"
echo "::endgroup::"

工作流运行日志中的可折叠组

在日志中屏蔽值

::add-mask::{value}

屏蔽值可阻止在日志中打印字符串或变量。 用空格分隔的每个屏蔽的词均替换为 * 字符。 您可以使用环境变量或字符串作为屏蔽的 value

屏蔽字符串的示例

当您在日志中打印 "Mona The Octocat" 时,您将看到 "***"

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

屏蔽环境变量的示例

当您在日志中打印变量 MY_NAME 或值 "Mona The Octocat" 时,您将看到 "***" 而不是 "Mona The Octocat"

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

停止和启动工作流程命令

::stop-commands::{endtoken}

停止处理任何工作流程命令。 此特殊命令可让您记录任何内容而不会意外运行工作流程命令。 例如,您可以停止记录以输出带有注释的整个脚本。

要停止处理工作流程命令,请将唯一的令牌传递给 stop-commands。 要继续处理工作流程命令,请传递用于停止工作流程命令的同一令牌。

警告: 请确保您使用的令牌是随机生成的,且对每次运行唯一。 如下面的示例所示,您可以为每次运行生成 github.token 的唯一哈希值。

::{endtoken}::

停止和启动工作流程命令的示例

jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: disable workflow commands
        run: |
          echo '::warning:: this is a warning'
          echo "::stop-commands::`echo -n ${{ github.token }} | sha256sum | head -c 64`"
          echo '::warning:: this will NOT be a warning'
          echo "::`echo -n ${{ github.token }} | sha256sum | head -c 64`::"
          echo '::warning:: this is a warning again'

Echoing command outputs

::echo::on
::echo::off

Enables or disables echoing of workflow commands. For example, if you use the set-output command in a workflow, it sets an output parameter but the workflow run's log does not show the command itself. If you enable command echoing, then the log shows the command, such as ::set-output name={name}::{value}.

Command echoing is disabled by default. However, a workflow command is echoed if there are any errors processing the command.

The add-mask, debug, warning, and error commands do not support echoing because their outputs are already echoed to the log.

You can also enable command echoing globally by turning on step debug logging using the ACTIONS_STEP_DEBUG secret. For more information, see "Enabling debug logging". In contrast, the echo workflow command lets you enable command echoing at a more granular level, rather than enabling it for every workflow in a repository.

Example toggling command echoing

jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: toggle workflow command echoing
        run: |
          echo '::set-output name=action_echo::disabled'
          echo '::echo::on'
          echo '::set-output name=action_echo::enabled'
          echo '::echo::off'
          echo '::set-output name=action_echo::disabled'

The step above prints the following lines to the log:

::set-output name=action_echo::enabled
::echo::off

Only the second set-output and echo workflow commands are included in the log because command echoing was only enabled when they were run. Even though it is not always echoed, the output parameter is set in all cases.

将值发送到 pre 和 post 操作

您可以使用 save-state 命令来创建环境变量,以便与工作流程的 pre:post: 操作共享。 例如,您可以使用 pre: 操作创建文件,将该文件位置传给 main: 操作,然后使用 post: 操作删除文件。 或者,您可以使用 main: 操作创建文件,将该文件位置传给 post: 操作,然后使用 post: 操作删除文件。

如果您有多个 pre:post: 操作,则只能访问使用了 save-state 的操作中的已保存值。 有关 post: 操作的更多信息,请参阅“GitHub Actions 的元数据语法”。

save-state 命令只能在操作内运行,并且对 YAML 文件不可用。 保存的值将作为环境值存储,带 STATE_ 前缀。

此示例使用 JavaScript 运行 save-state 命令。 由此生成的环境变量被命名为 STATE_processID,带 12345 的值:

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

然后,STATE_processID 变量将仅可被用于 main 操作下运行的清理脚本。 此示例在 main 中运行,并使用 JavaScript 显示分配给 STATE_processID 环境变量的值:

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

环境文件

在工作流程执行期间,运行器生成可用于执行某些操作的临时文件。 这些文件的路径通过环境变量显示。 写入这些文件时,您需要使用 UTF-8 编码,以确保正确处理命令。 多个命令可以写入同一个文件,用换行符分隔。

Warning: On Windows, legacy PowerShell (shell: powershell) does not use UTF-8 by default. 请确保使用正确的编码写入文件。 例如,在设置路径时需要设置 UTF-8 编码:

jobs:
  legacy-powershell-example:
    uses: windows-2019
    steps:
      - shell: powershell
        run: echo "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

Or switch to PowerShell Core, which defaults to UTF-8:

jobs:
  modern-pwsh-example:
    uses: windows-2019
    steps:
      - shell: pwsh
        run: echo "mypath" | Out-File -FilePath $env:GITHUB_PATH -Append # no need for -Encoding utf8

More detail about UTF-8 and PowerShell Core found on this great Stack Overflow answer:

Optional reading: The cross-platform perspective: PowerShell Core:

PowerShell is now cross-platform, via its PowerShell Core edition, whose encoding - sensibly - defaults to BOM-less UTF-8**, in line with Unix-like platforms.

设置环境变量

echo "{name}={value}" >> $GITHUB_ENV

为作业中接下来运行的任何步骤创建或更新环境变量。 创建或更新环境变量的步骤无法访问新值,但在作业中的所有后续步骤均可访问。 环境变量区分大小写,并且可以包含标点符号。

Note: Environment variables must be explicitly referenced using the env context in expression syntax or through use of the $GITHUB_ENV file directly; environment variables are not implicitly available in shell commands.

示例

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> $GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      echo "${{ env.action_state }}" # This will output 'yellow'

多行字符串

对于多行字符串,您可以使用具有以下语法的分隔符。

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

示例

在此示例中, 我们使用 EOF 作为分隔符,并将 JSON_RESPONSE 环境变量设置为 cURL 响应的值。

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

添加系统路径

echo "{path}" >> $GITHUB_PATH

Prepends a directory to the system PATH variable and automatically makes it available to all subsequent actions in the current job; the currently running action cannot access the updated path variable. 要查看作业的当前定义路径,您可以在步骤或操作中使用 echo "$PATH"

示例

此示例演示如何将用户 $HOME/.local/bin 目录添加到 PATH

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

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。