Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

此版本的 GitHub Enterprise 已停止服务 2023-01-18. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

GitHub Actions 的工作流命令

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

注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

关于工作流程命令

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

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

示例

Shell
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
pwsh
Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"

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

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

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

操作/工具包包含许多可作为工作流命令执行的函数。 使用 :: 语法来运行你的 YAML 文件中的工作流程命令;然后,通过 stdout 将这些命令发送给运行器。 例如,不要像下面这样使用代码来设置输出:

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

示例:设置值

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

YAML
      - 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 }}"
YAML
      - name: Set selected color
        run: Write-Output "::set-output name=SELECTED_COLOR::green"
        id: random-color-generator
      - name: Get color
        run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

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

工具包函数等效工作流程命令
core.addPath可使用环境文件 GITHUB_PATH 访问
core.debugdebug
core.noticenotice
core.errorerror
core.endGroupendgroup
core.exportVariable可使用环境文件 GITHUB_ENV 访问
core.getInput可使用环境变量 INPUT_{NAME} 访问
core.getState可使用环境变量 STATE_{NAME} 访问
core.isDebug可使用环境变量 RUNNER_DEBUG 访问

设置输出参数

设置操作的输出参数。

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

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

可以通过创建环境变量并在工作流命令中使用它,来转义用于设置输出参数的多行字符串。 有关详细信息,请参阅“设置环境变量”。

示例:设置输出参数

Shell
echo "::set-output name=action_fruit::strawberry"
pwsh
Write-Output "::set-output name=action_fruit::strawberry"

设置调试消息

将调试消息打印到日志。 必须创建一个名为 ACTIONS_STEP_DEBUG 且值为 true 的机密,才能在日志中查看此命令设置的调试消息。 有关详细信息,请参阅“启用调试日志记录”。

Code
::debug::{message}

示例:设置调试消息

Shell
echo "::debug::Set the Octocat variable"
pwsh
Write-Output "::debug::Set the Octocat variable"

设置通知消息

创建通知消息并将该消息打印到日志。 此消息将创建注释,该注释可将消息与存储库中的特定文件相关联。 或者,消息可以指定文件中的位置。

Code
::notice file={name},line={line},endLine={endLine},title={title}::{message}
参数
title自定义标题
file文件名
col列号(从 1 开始)
endColumn结束列号
line行号(从 1 开始)
endLine结束行号

示例:设置通知消息

Shell
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

设置警告消息

创建警告消息并将该消息打印到日志。 此消息将创建注释,该注释可将消息与存储库中的特定文件相关联。 或者,消息可以指定文件中的位置。

Code
::warning file={name},line={line},endLine={endLine},title={title}::{message}
参数
title自定义标题
file文件名
col列号(从 1 开始)
endColumn结束列号
line行号(从 1 开始)
endLine结束行号

示例:设置警告消息

Shell
echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

设置错误消息

创建错误消息并将该消息打印到日志。 此消息将创建注释,该注释可将消息与存储库中的特定文件相关联。 或者,消息可以指定文件中的位置。

Code
::error file={name},line={line},endLine={endLine},title={title}::{message}
参数
title自定义标题
file文件名
col列号(从 1 开始)
endColumn结束列号
line行号(从 1 开始)
endLine结束行号

示例:设置错误消息

Shell
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

对日志行分组

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

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

示例:对日志行进行分组

YAML
jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"
YAML
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::"

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

在日志中屏蔽值

Code
::add-mask::{value}

屏蔽值可阻止在日志中打印字符串或变量。 用空格分隔的每个屏蔽的词均替换为 * 字符。 可以使用环境变量或字符串作为屏蔽的 value。 当屏蔽某个值时,它将被视为机密,并将在运行器上进行修订。 例如,屏蔽某个值后,将无法将该值设置为输出。

示例:屏蔽字符串

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

Shell
echo "::add-mask::Mona The Octocat"
pwsh
Write-Output "::add-mask::Mona The Octocat"

警告:请确保先将机密注册到“add-mask”,然后再将其输出到生成日志中,或在任何其他工作流命令中使用它。

示例:屏蔽环境变量

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

YAML
jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"
YAML
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"

停止和启动工作流程命令

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

Code
::stop-commands::{endtoken}

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

警告:请确保你使用的令牌是随机生成的,且对每次运行唯一。

Code
::{endtoken}::

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

YAML
jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: Disable workflow commands
        run: |
          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-latest
    steps:
      - name: Disable workflow commands
        run: |
          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.'

回显命令输出

启用或禁用工作流程命令的回显。 例如,如果在工作流程中使用 set-output 命令,则会设置输出参数,但工作流程运行的日志不会显示命令本身。 如果启用命令回显,则日志会显示命令,例如 ::set-output name={name}::{value}

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

默认情况下,命令回显处于禁用状态。 但是,如果处理工作流命令时出现任何错误,则会回显该命令。

add-maskdebugwarningerror 命令不支持回显,因为它们的输出已经回显到日志中。

还可以通过使用 ACTIONS_STEP_DEBUG 密钥打开步骤调试日志记录来启用命令全局回显。 有关详细信息,请参阅“启用调试日志记录”。 相比之下,echo 工作流程命令允许你在更精细的级别启用命令回显,而不是为存储库中的每个工作流程启用它。

示例:切换命令回显

YAML
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'
YAML
jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: toggle workflow command echoing
        run: |
          write-output "::set-output name=action_echo::disabled"
          write-output "::echo::on"
          write-output "::set-output name=action_echo::enabled"
          write-output "::echo::off"
          write-output "::set-output name=action_echo::disabled"

上面的示例将以下行打印到日志中:

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

日志中仅包含第二个 set-outputecho 工作流程命令,因为命令回显仅在运行时启用。 即使它并不总是回显,输出参数在所有情况下都会被设置。

将值发送到 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

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

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

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

环境文件

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

以下示例中的大多数命令使用双引号来回显字符串,这将尝试为 shell 变量名称内插字符(如 $)。 若要始终在用引号引起来的字符串中使用文本值,可改为使用单引号。

注意:PowerShell 5.1 及更低版本 (shell: powershell) 默认不使用 UTF-8,因此必须指定 UTF-8 编码。 例如:

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

PowerShell Core 版本 6 及更高版本 (shell: pwsh) 默认使用 UTF-8。 例如:

YAML
jobs:
  powershell-core-example:
    runs-on: windows-latest
    steps:
      - shell: pwsh
        run: |
          "mypath" >> $env:GITHUB_PATH

设置环境变量

Shell
echo "{environment_variable_name}={value}" >> $GITHUB_ENV
  • 使用 PowerShell 版本 6 及更高版本:

    pwsh
    "{environment_variable_name}={value}" >> $env:GITHUB_ENV
  • 使用 PowerShell 版本 5.1 及更低版本:

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

通过定义或更新环境变量并将其写入 GITHUB_ENV 环境文件,可以使环境变量用于工作流程作业中的任何后续步骤。 创建或更新环境变量的步骤无法访问新值,但在作业中的所有后续步骤均可访问。 环境变量的名称区分大小写,您可以包含标点符号。 有关详细信息,请参阅“环境变量”。

示例

YAML
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'
YAML
steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" >> $env:GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      Write-Output "${{ env.action_state }}" # This will output 'yellow'

多行字符串

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

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

警告:请确保你使用的分隔符是随机生成的,且对每次运行唯一。 有关详细信息,请参阅“了解脚本注入的风险”。

示例

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

YAML
steps:
  - name: Set the value in bash
    id: step_one
    run: |
      echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
      curl https://example.com >> $GITHUB_ENV
      echo 'EOF' >> $GITHUB_ENV
YAML
steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      "JSON_RESPONSE<<EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "EOF" >> $env:GITHUB_ENV
    shell: pwsh

添加系统路径

为系统 PATH 变量预先设置一个目录,并自动使其可用于当前作业中的所有后续操作;当前运行的操作无法访问更新的路径变量。 要查看作业的当前定义路径,可以在步骤或操作中使用 echo "$PATH"

Shell
echo "{path}" >> $GITHUB_PATH
pwsh
"{path}" >> $env:GITHUB_PATH

示例

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

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

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

pwsh
"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH