注:GitHub Enterprise Server 2.22 上的 GitHub Actions 支持是有限的公测版。 测试已结束。 GitHub Actions 现在一般可用于 GitHub Enterprise Server 3.0 或更新版本。 更多信息请参阅 GitHub Enterprise Server 3.0 发行说明。
- 有关升级到 GitHub Enterprise Server 3.0 或更新版本的更多信息,请参阅“升级 GitHub Enterprise Server”。
- 有关在升级后配置 GitHub Actions 的更多信息,请参阅 GitHub Enterprise Server 3.0 的文档。
注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
关于工作流程命令
操作可以与运行器机器进行通信,以设置环境变量,其他操作使用的输出值,将调试消息添加到输出日志和其他任务。
工作流程命令使用特定格式的 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.addPath | |
add-path 访问 | |
core.debug | debug |
core.error | error |
core.endGroup | endgroup |
core.exportVariable | |
set-env 访问 | |
core.getInput | 可使用环境变量 INPUT_{NAME} 访问 |
core.getState | 可使用环境变量 STATE_{NAME} 访问 |
core.isDebug | 可使用环境变量 RUNNER_DEBUG 访问 |
core.saveState | save-state |
core.setFailed | 用作 ::error 和 exit 1 的快捷方式 |
core.setOutput | set-output |
core.setSecret | add-mask |
core.startGroup | 组 |
core.warning | 警告 |
设置环境变量
::set-env name={name}::{value}
为作业中接下来运行的任何步骤创建或更新环境变量。 The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. 环境变量区分大小写,并且可以包含标点符号。
示例
echo "::set-env name=action_state::yellow"
设置输出参数
::set-output name={name}::{value}
设置操作的输出参数。
(可选)您也可以在操作的元数据文件中声明输出参数。 更多信息请参阅“GitHub Actions 的元数据语法”。
示例
echo "::set-output name=action_fruit::strawberry"
添加系统路径
::add-path::{path}
为当前作业中的所有后续操作将目录添加到系统 PATH
变量之前。 当前运行的操作无法访问新路径变量。
示例
echo "::add-path::/path/to/dir"
设置调试消息
::debug::{message}
将调试消息打印到日志。 您可以创建名为 ACTIONS_STEP_DEBUG
、值为 true
的密码,才能在日志中查看通过此命令设置的调试消息。 更多信息请参阅“启用调试日志记录”。
示例
echo "::debug::Set the Octocat variable"
设置警告消息
::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 | | :- | :- | | file
| Filename | | col
| Column number, starting at 1 | | line
| Line number, starting at 1 |
示例
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 | | :- | :- | | file
| Filename | | col
| Column number, starting at 1 | | line
| Line number, starting at 1 |
示例
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
对日志行分组
::group::{title}
::endgroup::
在日志中创建一个可扩展的组。 要创建组,请使用 group
命令并指定 title
。 打印到 group
与 endgroup
命令之间日志的任何内容都会嵌套在日志中可扩展的条目内。
示例
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}
停止处理任何工作流程命令。 此特殊命令可让您记录任何内容而不会意外运行工作流程命令。 例如,您可以停止记录以输出带有注释的整个脚本。
To stop the processing of workflow commands, pass a unique token to stop-commands
. To resume processing workflow commands, pass the same token that you used to stop workflow commands.
Warning: Make sure the token you're using is randomly generated and unique for each run. As demonstrated in the example below, you can generate a unique hash of your github.token
for each run.
::{endtoken}::
Example stopping and starting workflow commands
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'
将值发送到 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);