GitHub Actions 的工作流命令

注意：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.debug`	`debug`
`core.notice`	`notice`
`core.error`	`error`
`core.endGroup`	`endgroup`
`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。在 group 和 endgroup 命令之间打印到日志的任何内容都嵌套在日志的可扩展条目中。

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-mask、debug、warning 和 error 命令不支持回显，因为它们的输出已经回显到日志中。

还可以通过使用 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-output 和 echo 工作流程命令，因为命令回显仅在运行时启用。即使它并不总是回显，输出参数在所有情况下都会被设置。

将值发送到 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 环境文件，可以使环境变量用于工作流程作业中的任何后续步骤。创建或更新环境变量的步骤无法访问新值，但在作业中的所有后续步骤均可访问。环境变量的名称区分大小写，您可以包含标点符号。有关详细信息，请参阅“变量”。

有关将环境变量写入 `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}

警告：请确保你使用的分隔符是随机生成的，且对每次运行唯一。有关详细信息，请参阅“GitHub Actions 的安全强化”。

多行字符串的示例

此示例为 $EOF 选择一个随机值作为分隔符，并将 JSON_RESPONSE 环境变量设置为 curl 响应的值。

YAML

steps:
  - name: Set the value in bash
    id: step_one
    run: |
      EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
      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: |
      -join (1..15 | ForEach {[char]((48..57)+(65..90)+(97..122) | Get-Random)}) | set EOF
      "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

GitHub Actions 的工作流命令

本文内容

关于工作流程命令

工作流命令的示例

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

示例：设置值

设置输出参数

示例：设置输出参数

设置调试消息

示例：设置调试消息

设置通知消息

示例：设置通知消息

设置警告消息

示例：设置警告消息

设置错误消息

示例：设置错误消息

对日志行分组

示例：对日志行进行分组

在日志中屏蔽值

示例：屏蔽字符串

示例：屏蔽环境变量

停止和启动工作流程命令

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

回显命令输出

示例：切换命令回显

将值发送到 pre 和 post 操作

环境文件

设置环境变量

有关将环境变量写入 GITHUB_ENV 的示例

多行字符串

多行字符串的示例

添加系统路径

有关添加系统路径的示例

有关将环境变量写入 `GITHUB_ENV` 的示例