在作业之前或之后运行脚本

脚本可以直接在作业之前或之后在自托管运行器上自动执行。

本文内容

关于作业前脚本和作业后脚本

可在作业运行之前或在作业完成运行之后，在自托管运行器上自动执行脚本。 可使用这些脚本来满足作业需求，例如生成或关闭运行器环境，或清理目录。 还可使用这些脚本来跟踪运行器使用情况的遥测数据。

当运行器上设置了特定环境变量时，自定义脚本会自动触发；环境变量必须包含该脚本的绝对路径。 有关详细信息，请参阅下面的“触发脚本”。

支持以下脚本语言：

  • Bash：使用 bash 并可以回退到 sh。 通过运行 -e {pathtofile} 执行。
  • PowerShell：使用 pwsh 并可以回退到 powershell。 通过运行 -command \". '{pathtofile}'\" 执行。

编写脚本

自定义脚本可以使用以下功能：

  • 变量：脚本有权访问默认变量。 完整的 Webhook 事件有效负载可在 GITHUB_EVENT_PATH 中找到。 有关详细信息，请参阅“在变量中存储信息”。
  • 工作流命令：脚本可以使用工作流命令。 有关详细信息，请参阅“GitHub Actions 的工作流命令”。 脚本还可以使用环境文件。 有关详细信息，请参阅“环境文件”。

脚本文件必须使用相关语言的文件扩展名（如 .sh 或 .ps1），这样才能成功运行。

Note

避免使用脚本将敏感信息输出到控制台，因为拥有存储库读取访问权限的任何人都可以在 UI 日志中查看输出。

处理退出代码

对于作业前脚本，退出代码 0 指示脚本成功完成并且作业随后继续运行。 如果存在任何其他退出代码，该作业将不会运行，并标记为失败。 要查看作业前脚本的结果，请检查日志中的 Set up runner 条目。 若要详细了解如何检查日志，请参阅“使用工作流运行日志”。

这些脚本不支持使用 continue-on-error 设置。

触发脚本

自定义脚本必须位于运行器上，但不应存储在 actions-runner 应用程序目录中。 脚本在运行运行器服务的服务帐户的安全性上下文中执行。

Note

触发的脚本是同步处理的，因此它们会在运行时阻止作业执行。

当运行器具有以下包含脚本绝对路径的环境变量时，脚本会自动执行：

  • ACTIONS_RUNNER_HOOK_JOB_STARTED：此环境变量中定义的脚本在作业分配给运行器之后且作业开始运行之前触发。
  • ACTIONS_RUNNER_HOOK_JOB_COMPLETED：在该工作流中定义所有步骤都运行完之后，此环境变量中指定的脚本在作业末尾触发。

要设置这些环境变量，可将它们添加到操作系统中，或将它们添加到自托管运行器应用程序目录（即运行器软件下载并解包到的目录）中名为 .env 的文件中。 例如，以下 .env 条目将让运行器在每个作业运行之前，自动运行一个在运行器计算机上保存为 /opt/runner/cleanup_script.sh 的脚本：

ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner/cleanup_script.sh

Note

ACTIONS_RUNNER_HOOK_JOB_COMPLETED 中定义的脚本在作业完成之前，在作业末尾执行。 这使得它并不适合可能中断运行器的用例，例如，在实施自动缩放时删除运行器计算机。

故障排除

权限被拒绝

如果尝试运行脚本时出现“权限被拒绝”错误，请确保脚本可执行。 例如，在 Linux 或 macOS 的终端中，可以使用以下命令让文件成为可执行文件。

chmod +x PATH/TO/FILE

有关使用工作流运行脚本的信息，请参阅“添加脚本到工作流程”。

无超时设置

目前没有可供 ACTIONS_RUNNER_HOOK_JOB_STARTED 或 ACTIONS_RUNNER_HOOK_JOB_COMPLETED 执行的脚本使用的超时设置。 因此，可以考虑向脚本添加超时处理。

查看工作流运行日志

要确认脚本是否正在执行，可查看该作业的日志。 脚本将在 Set up runner 或 Complete runner 的单独步骤中列出，具体取决于触发脚本的环境变量。 若要详细了解如何检查日志，请参阅“使用工作流运行日志”。