自托管运行程序参考

查找有关设置和使用自托管运行器的信息。

本文内容

自托管运行器机器的要求

只要符合以下要求，便可将计算机用作自托管运行程序：

  • 你可以在机器上安装和运行自托管运行器应用程序。 请参阅支持的操作系统和支持的处理器体系结构。
  • 计算机可与 GitHub Actions 通信。
  • 机器有足够的硬件资源来执行你计划运行的工作流程类型。 自托管运行器应用程序本身只需要很少的资源。
  • 如果你想运行使用 Docker 容器操作或服务容器的工作流程，你必须使用 Linux 机器并安装 Docker。

受支持的操作系统

Linux

  • Red Hat Enterprise Linux 8 或更高版本
  • CentOS 8 或更高版本
  • Oracle Linux 8 或更高版本
  • Fedora 29 或更高版本
  • Debian 10 或更高版本
  • Ubuntu 20.04 或更高版本
  • Linux Mint 20 或更高版本
  • openSUSE 15.2 或更高版本
  • SUSE Enterprise Linux (SLES) 15 SP2 或更高版本

Windows

  • Windows 10 64 位
  • Windows 11 64 位
  • Windows Server 2016 64 位
  • Windows Server 2019 64 位
  • Windows Server 2022 64 位

macOS

  • macOS 11.0 (Big Sur) 或更高版本

支持的处理器体系结构

  • x64 - Linux、macOS、Windows。
  • ARM64 - Linux、macOS。
  • ARM32 - Linux。

自托管运行器的路由优先级

将作业路由到自托管运行器时，GitHub 将查找与作业的 runs-on 标签和组匹配的运行器：

  • 如果 GitHub 找到一个在线的空闲运行器与作业的 runs-on 标签和组匹配，则作业将分配并发送到该运行器。
    • 如果运行器在 60 秒内未收到分配的任务，任务将被重新排队，以便新的运行器能够接纳它。
  • 如果 GitHub 找不到与作业的 runs-on 标签和组匹配的在线和空闲运行器，则作业将继续排队，直到某个运行器上线为止。
  • 如果作业排队的时间超过 24 小时，则作业将失败。

自动缩放

您可以自动增加或减少环境中自托管运行器的数量，以响应您收到的带特定标签的 web 挂钩事件。

支持的自动缩放解决方案

actions/actions-runner-controller (ARC) 项目是基于 Kubernetes 的运行器自动缩放程序。 GitHub 如果部署 ARC 的团队具有专业的 Kubernetes 知识和经验，则建议使用 ARC。

有关详细信息，请参阅 Actions Runner Controller 和 对 Actions Runner Controller 的支持。

使用临时运行器进行自动缩放

GitHub 建议使用临时的自托管运行器实现自动缩放；不建议使用持久的自托管运行器进行自动缩放。 在某些情况下， GitHub 无法保证作业在关闭时不会分配给持久性运行器。 对于临时运行器，这可以得到保证，因为 GitHub 只将一个作业分配给运行器。

这种方法允许您将运行器作为临时系统进行管理，因为您可以使用自动化为每个作业提供干净的环境。 这有助于限制以前工作中任何敏感资源的暴露，也有助于降低受损运行器获得新作业的风险。

警告

临时运行器的运行器应用程序日志文件必须转发到外部日志存储解决方案，以便进行故障排除和诊断。 虽然不需要部署临时运行器，但 GitHub 建议在生产环境中部署临时运行器自动缩放解决方案之前，确保在外部转发和保留运行器日志。 有关详细信息，请参阅“对自托管运行程序进行监视和故障排除”。

要将临时运行器添加到环境，请在使用 config.sh 注册运行器时包含 --ephemeral 参数。 例如：

./config.sh --url https://github.com/octo-org --token example-token --ephemeral

然后，GitHub Actions 服务将在处理完一个作业后自动取消注册运行器。 然后，您可以创建自己的自动化，在取消注册后擦除运行器。

注意

如果作业被标记为需要某种类型的运行器，但没有与之匹配的运行器，则作业在排队时不会立即失败。 相反，作业将保持排队状态，直到 24 小时超时期限到期。

或者，可以使用 REST API 创建临时的实时运行器。 有关详细信息，请参阅“自托管运行器的 REST API 终结点”。

自托管运行器上的运行器软件更新

默认情况下，每当有新版本的运行器软件可用时，自托管运行器将自动执行软件更新。 如果在容器中使用临时运行器，则当发布新的运行器版本时，这可能会导致重复的软件更新。 关闭自动更新允许你按照自己的计划直接更新容器映像上的运行器版本。

要关闭自动软件更新并自行安装软件更新，请在使用 config.sh 注册运行器时指定 --disableupdate 标志。 例如：

./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate

如果禁用自动更新，您仍必须定期更新运行器版本。 GitHub Actions 中的新功能需要同时更改 GitHub Actions 服务和运行器软件。 在没有软件更新的情况下，运行器可能无法正确处理利用 GitHub Actions 新功能的作业。

如果禁用自动更新，则需要在新版本可用后的 30 天内更新运行器版本。 你可能想要订阅actions/runner存储库中关于版本的通知。 有关详细信息，请参阅“配置通知”。

若要了解如何安装最新的运行器版本，请参阅最新版本的安装说明。

警告

为软件发布的任何更新（包括主要版本、次要版本或修补程序版本）都被视为可用更新。 注意：如果未在 30 天内执行软件更新，GitHub Actions 服务将不会将工作排队到运行器。 此外，如果需要关键安全更新，GitHub Actions 服务在更新之前不会将作业排队到运行器。

使用 Webhook 进行自动缩放

可使用从 workflow_job Webhook 接收的有效负载自行创建自动缩放环境。 此 Webhook 在存储库、组织和企业级别可用，并且此事件的有效负载包含一个 action 键，该键对应于工作流作业生命周期的各个阶段；例如，当作业是 queued、in_progress 和 completed 时。 然后，您必须创建自己的缩放自动化以响应这些 web 挂钩有效负载。

身份验证要求

可使用 API 注册和删除存储库和组织自托管运行器。 若要向 API 进行身份验证，自动缩放实现可以使用访问令牌或 GitHub 应用。

访问令牌将需要以下作用域：

要使用 GitHub 应用进行身份验证，必须为其分配以下权限：

  • 对于存储库，请分配 administration 权限。
  • 对于组织，请分配 organization_self_hosted_runners 权限。

可使用 API 注册和删除企业自托管运行器。 要向 API 进行身份验证，自动缩放实现可以使用访问令牌。

访问令牌将需要 manage_runners:enterprise 范围。

通信

自托管运行器连接到 你的 GitHub Enterprise Server 实例 以接收作业分配并下载新版本的运行器应用程序。

GitHub Actions 运行器应用程序是开源的。 可以参与 runner 存储库并在其中提交问题。 发布新版本后，运行器应用程序将在 24 小时内自动更新。

与 你的 GitHub Enterprise Server 实例 进行通信的要求

  • 自托管运行器应用程序必须在主机上运行才能接受和运行 GitHub Actions 作业。
  • GitHub Enterprise Server 必须通过 HTTP(S) 在 你的 GitHub Enterprise Server 实例 的主机名和 API 子域接受来自运行器的入站连接，并且运行器必须允许通过 HTTP(S) 与 你的 GitHub Enterprise Server 实例 的主机名和 API 子域建立出站连接。
  • 若要使缓存正常工作，运行器必须能够与 blob 存储进行通信，并直接从其中下载内容。

与 GitHub.com 的通信

自托管运行器不需要连接到 GitHub.com，除非您已启用自动访问 GitHub Enterprise Server 的 GitHub.com 操作。 有关详细信息，请参阅“关于在企业中使用操作”。

如果希望运行器连接到 GitHub.com，主机必须能够通过端口 80 建立出站 HTTP 连接，或通过端口 443 建立出站 HTTPS 连接。 若要确保通过 HTTPS 进行连接，请为 GitHub Enterprise Server 配置 TLS。 请参阅“配置 TLS”。

如果已启用自动访问 GitHub.com 操作，则自托管运行器将直接连接到 GitHub.com 以下载操作。 你必须确保机器具有适当的网络访问权限才可与以下列出的 GitHub URL 通信。

Shell
github.com
api.github.com
codeload.github.com
pkg.actions.githubusercontent.com

可以使用 REST API 获取关于 GitHub 的元信息，包括 GitHub 服务的 IP 地址和域详细信息。 API 的 actions_inbound 部分支持完全限定的域和通配符域。 完全限定的域指定完整的域名（例如 example.github.com），而通配符域则使用 * 来表示多个可能的子域（例如 *.github.com）。 下面列出了使用通配符域的自托管运行器要求的示例。 有关详细信息，请参阅“元数据的 REST API 终结点”。

Shell
github.com
*.github.com
*.githubusercontent.com
ghcr.io

注意

列出的一些域名使用 CNAME 记录配置。 一些防火墙可能要求你为所有 CNAME 记录递归添加规则。 请注意，CNAME 记录将来可能会改变，只有列出的域名将保持不变。