Note
GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。
关于工作流程命令
操作可以与运行器机器进行通信,以设置环境变量,其他操作使用的输出值,将调试消息添加到输出日志和其他任务。
大多数工作流程命令使用特定格式的 echo
命令,而其他工作流程则通过写入文件被调用。 有关详细信息,请参阅“环境文件”。
工作流命令的示例
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"
Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"
Note
工作流命令和参数名称不区分大小写。
Warning
如果使用命令提示符,则使用工作流命令时会忽略双引号字符 ("
)。
使用工作流程命令访问工具包函数
操作/工具包包含许多可作为工作流命令执行的函数。 使用 ::
语法来运行你的 YAML 文件中的工作流程命令;然后,通过 stdout
将这些命令发送给运行器。
例如,而不是使用代码创建错误注释,如下所示:
core.error('Missing semicolon', {file: 'app.js', startLine: 1})
core.error('Missing semicolon', {file: 'app.js', startLine: 1})
示例:为错误创建注释
可以在工作流中使用 error
命令来创建相同的错误注释:
- name: Create annotation for build error run: echo "::error file=app.js,line=1::Missing semicolon"
- name: Create annotation for build error
run: echo "::error file=app.js,line=1::Missing semicolon"
- name: Create annotation for build error run: Write-Output "::error file=app.js,line=1::Missing semicolon"
- name: Create annotation for build error
run: Write-Output "::error file=app.js,line=1::Missing semicolon"
下表显示了在工作流程中可用的工具包功能:
工具包函数 | 等效工作流程命令 |
---|---|
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 访问 |
core.summary | 可使用环境文件 GITHUB_STEP_SUMMARY 访问 |
core.saveState | 可使用环境文件 GITHUB_STATE 访问 |
core.setCommandEcho | echo |
core.setFailed | 用作 ::error 和 exit 1 的快捷方式 |
core.setOutput | 可使用环境文件 GITHUB_OUTPUT 访问 |
core.setSecret | add-mask |
core.startGroup | group |
core.warning | warning |
设置调试消息
将调试消息打印到日志。 必须创建一个名为 ACTIONS_STEP_DEBUG
且值为 true
的机密,才能在日志中查看此命令设置的调试消息。 有关详细信息,请参阅“启用调试日志记录”。
::debug::{message}
::debug::{message}
示例:设置调试消息
echo "::debug::Set the Octocat variable"
echo "::debug::Set the Octocat variable"
Write-Output "::debug::Set the Octocat variable"
Write-Output "::debug::Set the Octocat variable"
设置通知消息
创建通知消息并将该消息打印到日志。 此消息将创建注释,该注释可将消息与存储库中的特定文件相关联。 或者,消息可以指定文件中的位置。
::notice file={name},line={line},endLine={endLine},title={title}::{message}
::notice file={name},line={line},endLine={endLine},title={title}::{message}
参数 | 值 | 必须 | 默认 |
---|---|---|---|
title | 自定义标题 | 否 | 无 |
file | Filename | 否 | .github |
col | 列号(从 1 开始) | 否 | 无 |
endColumn | 结束列号 | 否 | 无 |
line | 行号(从 1 开始) | 否 | 1 |
endLine | 结束行号 | 否 | 1 |
示例:设置通知消息
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
设置警告消息
创建警告消息并将该消息打印到日志。 此消息将创建注释,该注释可将消息与存储库中的特定文件相关联。 或者,消息可以指定文件中的位置。
::warning file={name},line={line},endLine={endLine},title={title}::{message}
::warning file={name},line={line},endLine={endLine},title={title}::{message}
参数 | 值 | 必须 | 默认 |
---|---|---|---|
title | 自定义标题 | 否 | 无 |
file | Filename | 否 | .github |
col | 列号(从 1 开始) | 否 | 无 |
endColumn | 结束列号 | 否 | 无 |
line | 行号(从 1 开始) | 否 | 1 |
endLine | 结束行号 | 否 | 1 |
示例:设置警告消息
echo "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
echo "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
设置错误消息
创建错误消息并将该消息打印到日志。 此消息将创建注释,该注释可将消息与存储库中的特定文件相关联。 或者,消息可以指定文件中的位置。
::error file={name},line={line},endLine={endLine},title={title}::{message}
::error file={name},line={line},endLine={endLine},title={title}::{message}
参数 | 值 | 必须 | 默认 |
---|---|---|---|
title | 自定义标题 | 否 | 无 |
file | Filename | 否 | .github |
col | 列号(从 1 开始) | 否 | 无 |
endColumn | 结束列号 | 否 | 无 |
line | 行号(从 1 开始) | 否 | 1 |
endLine | 结束行号 | 否 | 1 |
示例:设置错误消息
echo "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
echo "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
Write-Output "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
Write-Output "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon"
对日志行分组
在日志中创建一个可扩展的组。 若要创建组,请使用 group
命令并指定一个 title
。 在 group
和 endgroup
命令之间打印到日志的任何内容都嵌套在日志的可扩展条目中。
::group::{title} ::endgroup::
::group::{title}
::endgroup::
示例:对日志行进行分组
jobs: bash-example: runs-on: ubuntu-latest steps: - name: Group of log lines run: | echo "::group::My title" echo "Inside group" echo "::endgroup::"
jobs:
bash-example:
runs-on: ubuntu-latest
steps:
- name: Group of log lines
run: |
echo "::group::My title"
echo "Inside group"
echo "::endgroup::"
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::"
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::"
在日志中屏蔽值
::add-mask::{value}
::add-mask::{value}
屏蔽值可阻止在日志中打印字符串或变量。 用空格分隔的每个屏蔽的词均替换为 *
字符。 可以使用环境变量或字符串作为屏蔽的 value
。 当屏蔽某个值时,它将被视为机密,并将在运行器上进行修订。 例如,屏蔽某个值后,将无法将该值设置为输出。
示例:屏蔽字符串
在日志中打印 "Mona The Octocat"
时,你将看到 "***"
。
echo "::add-mask::Mona The Octocat"
echo "::add-mask::Mona The Octocat"
Write-Output "::add-mask::Mona The Octocat"
Write-Output "::add-mask::Mona The Octocat"
Warning
请确保先将机密注册到“add-mask”,然后再将其输出到生成日志中,或在任何其他工作流命令中使用它。
示例:屏蔽环境变量
在日志中打印变量 MY_NAME
或值 "Mona The Octocat"
时,你将看到 "***"
而不是 "Mona The Octocat"
。
jobs: bash-example: runs-on: ubuntu-latest env: MY_NAME: "Mona The Octocat" steps: - name: bash-version run: echo "::add-mask::$MY_NAME"
jobs:
bash-example:
runs-on: ubuntu-latest
env:
MY_NAME: "Mona The Octocat"
steps:
- name: bash-version
run: echo "::add-mask::$MY_NAME"
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"
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"
示例:在单个作业中屏蔽生成的输出
如果不需要将机密从一个作业传递到另一个作业,则可以:
- 生成机密(但不输出机密)。
- 使用
add-mask
屏蔽。 - 使用
GITHUB_OUTPUT
可将机密用于作业中的其他步骤。
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 }}"
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 }}"
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 }}"
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 }}"
示例:在作业或工作流之间屏蔽和传递机密
如果要在作业或工作流之间传递屏蔽的机密,则应将该机密存储在某个存储位置,然后在后续作业或工作流中检索该机密。
设置
- 设置机密存储以存储将在工作流期间生成的机密。 例如,保管库。
- 生成用于读取和写入该机密存储的密钥。 将密钥存储为存储库机密。 在以下示例工作流中,机密名称为
SECRET_STORE_CREDENTIALS
。 有关详细信息,请参阅“在 GitHub Actions 中使用机密”。
Workflow
Note
此工作流使用虚构机密存储 secret-store
,其中包含虚构命令 store-secret
和 retrieve-secret
。 some/secret-store@ 27b31702a0e7fc50959f5ad993c78deac1bdfc29
是一个虚构的操作,用于安装 secret-store
应用程序并将其配置为使用 credentials
连接到 instance
。
on: push jobs: secret-generator: runs-on: ubuntu-latest outputs: handle: ${{ steps.generate-secret.outputs.handle }} steps: - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29 with: credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }} instance: ${{ secrets.SECRET_STORE_INSTANCE }} - name: generate secret id: 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@27b31702a0e7fc50959f5ad993c78deac1bdfc29 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"
on: push
jobs:
secret-generator:
runs-on: ubuntu-latest
outputs:
handle: ${{ steps.generate-secret.outputs.handle }}
steps:
- uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29
with:
credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
instance: ${{ secrets.SECRET_STORE_INSTANCE }}
- name: generate secret
id: 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@27b31702a0e7fc50959f5ad993c78deac1bdfc29
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"
on: push jobs: secret-generator: runs-on: ubuntu-latest steps: - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29 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@27b31702a0e7fc50959f5ad993c78deac1bdfc29 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"
on: push
jobs:
secret-generator:
runs-on: ubuntu-latest
steps:
- uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29
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@27b31702a0e7fc50959f5ad993c78deac1bdfc29
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"
停止和启动工作流程命令
停止处理任何工作流程命令。 此特殊命令可让您记录任何内容而不会意外运行工作流程命令。 例如,您可以停止记录以输出带有注释的整个脚本。
::stop-commands::{endtoken}
::stop-commands::{endtoken}
要停止处理工作流程命令,请将唯一的令牌传递给 stop-commands
。 要继续处理工作流程命令,请传递用于停止工作流程命令的同一令牌。
Warning
请确保你使用的令牌是随机生成的,且对每次运行唯一。
::{endtoken}::
::{endtoken}::
示例:停止和启动工作流程命令
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.'
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.'
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.'
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
:
import * as fs from 'fs' import * as os from 'os' fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, { encoding: 'utf8' })
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
环境变量的值:
console.log("The running PID from the main action is: " + process.env.STATE_processID);
console.log("The running PID from the main action is: " + process.env.STATE_processID);
环境文件
在工作流程执行期间,运行器生成可用于执行某些操作的临时文件。 可以使用 GitHub 的默认环境变量访问和编辑这些文件的路径。 请参阅“在变量中存储信息”。 写入这些文件时,您需要使用 UTF-8 编码,以确保正确处理命令。 多个命令可以写入同一个文件,用换行符分隔。
要在 GitHub Action 中使用环境变量,请使用特定的 GitHub Actions 命令创建或修改 .env
文件。
操作步骤如下:
name: Example Workflow for Environment Files on: push jobs: set_and_use_env_vars: runs-on: ubuntu-latest steps: - name: Set environment variable run: echo "MY_ENV_VAR=myValue" >> $GITHUB_ENV - name: Use environment variable run: | echo "The value of MY_ENV_VAR is $MY_ENV_VAR"
name: Example Workflow for Environment Files
on: push
jobs:
set_and_use_env_vars:
runs-on: ubuntu-latest
steps:
- name: Set environment variable
run: echo "MY_ENV_VAR=myValue" >> $GITHUB_ENV
- name: Use environment variable
run: |
echo "The value of MY_ENV_VAR is $MY_ENV_VAR"
另一个示例是使用它来存储生成时间戳、提交 SHA 或项目名称等元数据:
steps: - name: Store build timestamp run: echo "BUILD_TIME=$(date +'%T')" >> $GITHUB_ENV - name: Deploy using stored timestamp run: echo "Deploying at $BUILD_TIME"
steps:
- name: Store build timestamp
run: echo "BUILD_TIME=$(date +'%T')" >> $GITHUB_ENV
- name: Deploy using stored timestamp
run: echo "Deploying at $BUILD_TIME"
Note
PowerShell 5.1 及更低版本 (shell: powershell
) 默认不使用 UTF-8,因此必须指定 UTF-8 编码。 例如:
jobs: legacy-powershell-example: runs-on: windows-latest steps: - shell: powershell run: | "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
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。 例如:
jobs: powershell-core-example: runs-on: windows-latest steps: - shell: pwsh run: | "mypath" >> $env:GITHUB_PATH
jobs:
powershell-core-example:
runs-on: windows-latest
steps:
- shell: pwsh
run: |
"mypath" >> $env:GITHUB_PATH
设置环境变量
Note
为了避免问题,无论所用操作系统和 shell 的行为为何,最好将环境变量视为区分大小写。
echo "{environment_variable_name}={value}" >> "$GITHUB_ENV"
echo "{environment_variable_name}={value}" >> "$GITHUB_ENV"
-
使用 PowerShell 版本 6 及更高版本:
PowerShell "{environment_variable_name}={value}" >> $env:GITHUB_ENV
"{environment_variable_name}={value}" >> $env:GITHUB_ENV
-
使用 PowerShell 版本 5.1 及更低版本:
PowerShell "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
"{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
通过定义或更新环境变量并将其写入 GITHUB_ENV
环境文件,可以使环境变量用于工作流程作业中的任何后续步骤。 创建或更新环境变量的步骤无法访问新值,但在作业中的所有后续步骤均可访问。
不能覆盖名为 GITHUB_*
和 RUNNER_*
的默认环境变量的值。 目前可以覆盖 CI
变量的值。 但是,并不能保证这总是可行。 有关默认环境变量的更多信息,请参阅“在变量中存储信息”。
Note
由于安全限制,GITHUB_ENV
不能用于设置 NODE_OPTIONS
环境变量。
有关将环境变量写入 GITHUB_ENV
的示例
steps: - name: Set the value id: step_one run: | echo "action_state=yellow" >> "$GITHUB_ENV" - name: Use the value id: step_two run: | printf '%s\n' "$action_state" # This will output 'yellow'
steps:
- name: Set the value
id: step_one
run: |
echo "action_state=yellow" >> "$GITHUB_ENV"
- name: Use the value
id: step_two
run: |
printf '%s\n' "$action_state" # This will output 'yellow'
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'
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'
多行字符串
对于多行字符串,您可以使用具有以下语法的分隔符。
{name}<<{delimiter} {value} {delimiter}
{name}<<{delimiter}
{value}
{delimiter}
Warning
确保使用的分隔符不会出现在值内的单独一行中。 如果值是完全任意的,则不应使用此格式。 请改为将值写入文件。
多行字符串的示例
此示例使用 EOF
作为分隔符,并将 JSON_RESPONSE
环境变量设置为 curl
响应的值。
steps: - name: Set the value in bash id: step_one run: | { echo 'JSON_RESPONSE<<EOF' curl https://example.com echo EOF } >> "$GITHUB_ENV"
steps:
- name: Set the value in bash
id: step_one
run: |
{
echo 'JSON_RESPONSE<<EOF'
curl https://example.com
echo EOF
} >> "$GITHUB_ENV"
steps: - name: Set the value in pwsh id: step_one run: | $EOF = (New-Guid).Guid "JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV "$EOF" >> $env:GITHUB_ENV shell: pwsh
steps:
- name: Set the value in pwsh
id: step_one
run: |
$EOF = (New-Guid).Guid
"JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV
(Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
"$EOF" >> $env:GITHUB_ENV
shell: pwsh
设置输出参数
设置步骤的输出参数。 请注意,此步骤需要定义一个 id
以稍后检索输出值。 可以使用“多行字符串”部分中用于定义多行环境变量的相同技术设置多行输出值。
echo "{name}={value}" >> "$GITHUB_OUTPUT"
echo "{name}={value}" >> "$GITHUB_OUTPUT"
"{name}=value" >> $env:GITHUB_OUTPUT
"{name}=value" >> $env:GITHUB_OUTPUT
有关设置输出参数的示例
此示例演示如何设置 SELECTED_COLOR
输出参数,然后检索它:
- name: Set color id: color-selector run: echo "SELECTED_COLOR=green" >> "$GITHUB_OUTPUT" - name: Get color env: SELECTED_COLOR: ${{ steps.color-selector.outputs.SELECTED_COLOR }} run: echo "The selected color is $SELECTED_COLOR"
- name: Set color
id: color-selector
run: echo "SELECTED_COLOR=green" >> "$GITHUB_OUTPUT"
- name: Get color
env:
SELECTED_COLOR: ${{ steps.color-selector.outputs.SELECTED_COLOR }}
run: echo "The selected color is $SELECTED_COLOR"
此示例演示如何设置 SELECTED_COLOR
输出参数,然后检索它:
- name: Set color id: color-selector run: | "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT - name: Get color env: SELECTED_COLOR: ${{ steps.color-selector.outputs.SELECTED_COLOR }} run: Write-Output "The selected color is $env:SELECTED_COLOR"
- name: Set color
id: color-selector
run: |
"SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT
- name: Get color
env:
SELECTED_COLOR: ${{ steps.color-selector.outputs.SELECTED_COLOR }}
run: Write-Output "The selected color is $env:SELECTED_COLOR"
添加作业摘要
echo "{markdown content}" >> $GITHUB_STEP_SUMMARY
echo "{markdown content}" >> $GITHUB_STEP_SUMMARY
"{markdown content}" >> $env:GITHUB_STEP_SUMMARY
"{markdown content}" >> $env:GITHUB_STEP_SUMMARY
可以为每个作业设置一些自定义 Markdown,以便在工作流运行的摘要页上显示该作业。 可以使用作业摘要来显示和分组唯一内容,例如测试结果摘要,以便查看工作流运行结果的某人无需进入日志即可查看与运行相关的重要信息,例如失败。
作业摘要支持 GitHub 风格的 Markdown,你可以将 Markdown 内容添加到 GITHUB_STEP_SUMMARY
环境文件中的某个步骤。 GITHUB_STEP_SUMMARY
对于作业中的每个步骤都是唯一的。 有关 GITHUB_STEP_SUMMARY
引用的每步文件的详细信息,请参阅“环境文件”。
作业完成后,作业中所有步骤的摘要将分组到单个作业摘要中,并在工作流运行摘要页上显示。 如果多个作业生成摘要,则作业摘要按作业完成时间排序。
有关添加作业摘要的示例
echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY
echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY
"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY
"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY
多行 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
覆盖作业摘要
要清除当前步骤的所有内容,可以使用 >
覆盖 Bash 中任何以前添加的内容,或删除 PowerShell 中的 -Append
有关覆盖作业摘要的示例
- 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
Remove-Item $env:GITHUB_STEP_SUMMARY
完成步骤后,将上传作业摘要,后续步骤无法修改以前上传的 Markdown 内容。 摘要会自动屏蔽可能意外添加的任何机密。 如果作业摘要包含必须删除的敏感信息,则可以删除整个工作流运行,以删除其所有作业摘要。 有关详细信息,请参阅“删除工作流程运行”。
步骤隔离和限制
作业摘要在步骤之间隔离,每个步骤限制为最大大小 1MiB。 在步骤之间强制实施隔离,以便单个步骤中可能存在格式错误的 Markdown 无法中断后续步骤的 Markdown 呈现。 如果为步骤添加了超过 1MiB 的内容,则步骤的上传将失败,并且将创建错误注释。 作业摘要的上传失败不会影响步骤或作业的整体状态。 每个作业最多显示步骤中的 20 个作业摘要。
添加系统路径
为系统 PATH
变量预先设置一个目录,并自动使其可用于当前作业中的所有后续操作;当前运行的操作无法访问更新的路径变量。 要查看作业的当前定义路径,可以在步骤或操作中使用 echo "$PATH"
。
有关添加系统路径的示例
此示例演示如何将用户 $HOME/.local/bin
目录添加到 PATH
:
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
此示例演示如何将用户 $env:HOMEPATH/.local/bin
目录添加到 PATH
:
"$env:HOMEPATH/.local/bin" | Out-File -FilePath "$env:GITHUB_PATH" -Append
"$env:HOMEPATH/.local/bin" | Out-File -FilePath "$env:GITHUB_PATH" -Append