自托管运行程序参考

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

在本文中

自托管运行器机器的要求

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

  • 你可以在机器上安装和运行自托管运行器应用程序。 请参阅支持的操作系统和支持的处理器体系结构。
  • 机器可以与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、Windows（当前在 公开预览）。
  • ARM32 - Linux。

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

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

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

自动缩放

自动缩放允许你根据需求动态调整自托管运行器的数量。 这有助于优化资源利用率，并确保在高峰时段有足够的运行程序容量，同时在低活动期间降低成本。 有多种方法可实现自托管运行器的自动缩放，每种方法在复杂性、可靠性和响应性方面都有不同的权衡。

Actions Runner Controller

GitHub 托管的运行器会根据您的需求自动进行弹性扩展。 GitHub 托管的运行器可以作为开发或实施弹性扩展解决方案的低维护成本且经济高效的替代方案。 有关详细信息，请参阅“GitHub 托管的运行程序”。

Actions Runner Controller (ARC) 是 GitHub 规模集 API 的参考实现，也是用于对自托管运行器进行自动缩放的推荐 Kubernetes 解决方案。 ARC 为在 Kubernetes 环境中运行 GitHub Actions 的团队提供了一套完整的、可用于生产环境的自动缩放解决方案。

GitHub 建议拥有 Kubernetes 基础架构且团队具备 Kubernetes 专业知识的组织使用 ARC。 ARC 处理群集中运行器的整个生命周期，从预配到作业执行再到清理。

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

GitHub Actions 运行器规模集客户端

GitHub Actions 运行程序规模集客户端是基于 Go 的独立模块，它使平台团队、集成商和基础结构提供商能够跨 VM、容器、本地基础结构和云服务为 GitHub Actions 运行程序生成自定义自动缩放解决方案，并支持 Windows、Linux 和 macOS 平台。

客户端 GitHub 负责统筹处理与规模集相关的 API 交互，而基础结构预配则由你负责。 您定义运行器如何创建、扩展和销毁，并配置具有多个标签的运行器，以便灵活地路由和定向作业。 这使组织能够对运行器生命周期管理进行精细控制，并获得作业执行的实时遥测。

客户端设计为使用基本配置开箱即用，使团队能够快速实现自动缩放。 但是，其真正的能力在于其灵活性，客户端可以扩展和自定义，以满足每个组织的特定基础结构要求、合规性约束和操作工作流。 无论需要简单的缩放逻辑还是复杂的多环境预配策略，客户端都适应你的需求。

GitHub Actions 运行器扩展集客户端是一个开源项目。 actions/scaleset 仓库 包含完整的源代码、全面的文档和实用示例，帮助你快速上手。 你将找到实现指南、各种基础结构方案的示例配置，以及演示如何将客户端与不同的预配系统集成的参考体系结构。 存储库还包括为有兴趣扩展客户端或与社区共享其自动缩放模式的团队提供指南。

注意： Runner Scale Set Client 并不是 Actions Runner Controller（ARC）的替代方案；ARC 仍然是规模集 API 的参考实现，也是用于运行器自动扩缩的推荐 Kubernetes 解决方案。 相反，客户端是一种补充工具，用于与相同的规模集 API 进行连接，以在 Kubernetes 外部生成自定义自动缩放解决方案。

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

GitHub 建议使用临时自托管运行器实现自动缩放；不建议使用持久性自托管运行器进行自动缩放。 在某些情况下，GitHub 无法保证任务不会在持久化运行器关闭期间被分配给它们。 使用临时运行程序可以保证这一点，因为 GitHub 只向运行程序分配一个作业。

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

警告

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

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

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

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

注意

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

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

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

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

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

./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 挂钩有效负载。

注意： 此方法依赖于 Webhook 交付的时间线来做出缩放决策，这可能会导致延迟和可靠性问题。 请考虑将 操作控制器 或 规模集客户端 用于更大规模的自动缩放方案。

身份验证要求

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

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

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

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

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

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

通信

自托管运行器连接到 GitHub 以接收任务分配并下载运行器应用程序的新版本。

GitHub Actions 运行器应用程序是开源的。 可以参与 runner 存储库并在其中提交问题。 发布新版本后，运行器应用程序会在有作业分配给该运行器时自动更新；如果该运行器尚未被分配任何作业，则会在发布后一周内自动更新。

与 、GitHub、 通信的要求

  • 自托管运行器应用程序必须在主机上运行，才能接受并运行 GitHub Actions 任务。
  • 主机必须具备适当的网络访问权限，且上传和下载速度至少达到每秒 70 千比特。
  • 主机必须能够通过端口 443 建立出站 HTTPS 连接。
  • 根据分配给您的自托管运行器的流程功能，主机必须能够与以下列出的 GitHub 域名进行通信。

按功能划分的可访问域

注意

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

注意

如果您使用 带有数据驻留权的 GitHub Enterprise Cloud，您的运行器必须与以下列出的主机名之外的其他主机名进行通信。 有关完整的网络要求，请参阅 GHE.com 的网络详细信息。

基本操作所需：

Shell
github.com
api.github.com
*.actions.githubusercontent.com

下载操作所需内容：

Shell
codeload.github.com

上传/下载作业摘要、工作流项目和缓存时需要：

Shell
results-receiver.actions.githubusercontent.com
*.blob.core.windows.net

运行器版本更新所需：

Shell
objects.githubusercontent.com
objects-origin.githubusercontent.com
github-releases.githubusercontent.com
github-registry-files.githubusercontent.com

检索 OIDC 令牌时需要：

Shell
*.actions.githubusercontent.com

下载软件包或将软件包或容器发布到 GitHub Packages 时所需：

Shell
*.pkg.github.com
pkg-containers.githubusercontent.com
ghcr.io

需要用于 Git 大型文件存储

Shell
github-cloud.githubusercontent.com
github-cloud.s3.amazonaws.com

需要用于 Dependabot updates 的作业

Shell
dependabot-actions.githubapp.com

下载发布资产所需：

Shell
release-assets.githubusercontent.com

VNet 需要：

Shell
api.snapcraft.io

此外，你的工作流程可能需要访问其他网络资源。

如果您为 GitHub 组织或企业账户使用 IP 地址白名单，则必须将自托管运行器的 IP 地址添加到白名单中。 请参阅 GitHub Enterprise Cloud 文档中的管理组织的允许 IP 地址或强制执行企业安全设置策略