Skip to main content
我们经常发布文档更新,此页面的翻译可能仍在进行中。 有关最新信息,请访问英语文档

GitHub Actions 的工作流命令

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

关于工作流程命令

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

大多数工作流程命令使用特定格式的 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.error('Missing semicolon', {file: 'app.js', startLine: 1})

示例:为错误创建注释

可以在工作流中使用 error 命令来创建相同的错误注释:

YAML
      - name: Create annotation for build error
        run: echo "::error file=app.js,line=1::Missing semicolon"
YAML
      - name: Create annotation for build error
        run: Write-Output "::error file=app.js,line=1::Missing semicolon"

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

工具包函数等效工作流程命令
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 访问
core.summary可使用环境文件访问 GITHUB_STEP_SUMMARY
core.saveState可使用环境文件访问 GITHUB_STATE
core.setCommandEchoecho
core.setFailed用作 ::errorexit 1 的快捷方式
core.setOutput可使用环境文件访问 GITHUB_OUTPUT
core.setSecretadd-mask
core.startGroupgroup
core.warningwarning

设置调试消息

将调试消息打印到日志。 必须创建一个名为 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"

示例:在单个作业中屏蔽生成的输出

如果不需要将机密从一个作业传递到另一个作业,则可以:

  1. 生成机密(但不输出机密)。

  2. 使用 add-mask 屏蔽。

  3. 使用 GITHUB_OUTPUT 可将机密用于作业中的其他步骤。

YAML
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 }}"
YAML
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: |
          Set-Variable -Name TheSecret -Value (Get-Random)
          Write-Output "::add-mask::$TheSecret"
          "secret-number=$TheSecret" >> $env:GITHUB_OUTPUT
      - name: Use that secret output (protected by a mask)
        shell: pwsh
        run: |
          Write-Output "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"

示例:在作业或工作流之间屏蔽和传递机密

如果要在作业或工作流之间传递屏蔽的机密,则应将该机密存储在某个存储位置,然后在后续作业或工作流中检索该机密。

设置

  1. 设置机密存储以存储将在工作流期间生成的机密。 例如,保管库。
  2. 生成用于读取和写入该机密存储的密钥。 将密钥存储为存储库机密。 在以下示例工作流中,机密名称为 SECRET_STORE_CREDENTIALS。 有关详细信息,请参阅“加密机密”。

工作流

注意:此工作流使用虚构机密存储 secret-store,其中包含虚构命令 store-secretretrieve-secretsome/secret-store@ 27b31702a0e7fc50959f5ad993c78deac1bdfc29 是一个虚构的操作,用于安装 secret-store 应用程序并将其配置为使用 credentials 连接到 instance

YAML
on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      shell: bash
      run: |
        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-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: bash
      run: |
        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: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      shell: pwsh
      run: |
        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_OUTPUT
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: pwsh
      run: |
        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"

停止和启动工作流程命令

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

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.'

将值发送到 pre 和 post 操作

通过写入位于 GITHUB_STATE 的文件,可以创建用于与工作流的 pre:post: 操作共享的环境变量,。 例如,可以使用 pre: 操作创建文件,将文件位置传递给 main: 操作,然后使用 post: 操作删除该文件。 或者,可以使用 main: 操作创建文件,将文件位置传递给 post: 操作,同样使用 post: 操作删除文件。

如果有多个 pre:post: 操作,那就只能访问使用了 它被写入其中的操作中GITHUB_STATE。 有关 post: 操作的详细信息,请参阅“GitHub Actions 的元数据语法”。

GITHUB_STATE 文件仅在操作中可用。 保存的值将作为环境值存储,带 STATE_ 前缀。

此示例使用 JavaScript 写入 GITHUB_STATE 文件。 生成的环境变量名为 STATE_processID,值为 12345

JavaScript
import * as fs from 'fs'
import * as os from 'os'

fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, {
  encoding: 'utf8'
})

然后,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

设置输出参数

设置步骤的输出参数。 请注意,此步骤需要定义一个 id 以稍后检索输出值。 可以使用“多行字符串”部分中用于定义多行环境变量的相同技术设置多行输出值。

Shell
echo "{name}={value}" >> "$GITHUB_OUTPUT"
pwsh
"{name}=value" >> $env:GITHUB_OUTPUT

有关设置输出参数的示例

此示例演示如何设置 SELECTED_COLOR 输出参数,然后检索它:

YAML
      - name: Set color
        id: random-color-generator
        run: echo "SELECTED_COLOR=green" >> "$GITHUB_OUTPUT"
      - name: Get color

        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

此示例演示如何设置 SELECTED_COLOR 输出参数,然后检索它:

YAML
      - name: Set color
        id: random-color-generator
        run: |
            "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT
      - name: Get color

        run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

添加作业摘要

Shell
echo "{markdown content}" >> $GITHUB_STEP_SUMMARY
pwsh
"{markdown content}" >> $env:GITHUB_STEP_SUMMARY

可以为每个作业设置一些自定义 Markdown,以便在工作流运行的摘要页上显示该作业。 可以使用作业摘要来显示和分组唯一内容,例如测试结果摘要,以便查看工作流运行结果的某人无需进入日志即可查看与运行相关的重要信息,例如失败。

作业摘要支持 GitHub 风格的 Markdown,你可以将 Markdown 内容添加到 GITHUB_STEP_SUMMARY 环境文件中的某个步骤。 GITHUB_STEP_SUMMARY 对于作业中的每个步骤都是唯一的。 有关 GITHUB_STEP_SUMMARY 引用的每步文件的详细信息,请参阅“环境文件”。

作业完成后,作业中所有步骤的摘要将分组到单个作业摘要中,并在工作流运行摘要页上显示。 如果多个作业生成摘要,则作业摘要按作业完成时间排序。

有关添加作业摘要的示例

Shell
echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY
pwsh
"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY

工作流运行的摘要页的屏幕截图。 在“示例摘要”下是“Hello world!” 和火箭表情符号。

多行 Markdown 内容

对于多行 Markdown 内容,可以使用 >> 为当前步骤连续附加内容。 每次追加操作时,都会自动添加换行符。

多行 Markdown 内容的示例

- name: Generate list using Markdown
  run: |
    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: Generate list using Markdown
  run: |
    "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

覆盖作业摘要

若要清除当前步骤的所有内容,可以使用 > 覆盖任何以前添加的内容。

有关覆盖作业摘要的示例

- name: Overwrite Markdown
  run: |
    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: Overwrite Markdown
  run: |
    "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

删除作业摘要

若要完全删除当前步骤的摘要,可以删除 GITHUB_STEP_SUMMARY 引用的文件。

有关删除作业摘要的示例

- name: Delete all summary content
  run: |
    echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY
    rm $GITHUB_STEP_SUMMARY
- name: Delete all summary content
  run: |
    "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY
    rm $env:GITHUB_STEP_SUMMARY

完成步骤后,将上传作业摘要,后续步骤无法修改以前上传的 Markdown 内容。 摘要会自动屏蔽可能意外添加的任何机密。 如果作业摘要包含必须删除的敏感信息,则可以删除整个工作流运行,以删除其所有作业摘要。 有关详细信息,请参阅“删除工作流程运行”。

步骤隔离和限制

作业摘要在步骤之间隔离,每个步骤限制为最大大小 1MiB。 在步骤之间强制实施隔离,以便单个步骤中可能存在格式错误的 Markdown 无法中断后续步骤的 Markdown 呈现。 如果为步骤添加了超过 1MiB 的内容,则步骤的上传将失败,并且将创建错误注释。 作业摘要的上传失败不会影响步骤或作业的整体状态。 每个作业最多显示步骤中的 20 个作业摘要。

添加系统路径

为系统 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