自托管运行程序参考

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

在本文中

自托管运行器机器的要求

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

  • 你可以在机器上安装和运行自托管运行器应用程序。 请参阅支持的操作系统和支持的处理器体系结构。
  • 计算机可与 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 小时，则作业将失败。

自动缩放

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

数据变量.product.prodname_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 的模块，它使平台团队、集成商和基础设施提供商能够为 GitHub Actions 运行器在虚拟机、容器、本地基础设施和云服务中构建自定义自动扩展解决方案，并支持 Windows、Linux 和 macOS 平台。

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

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

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

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

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

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

          **注意：** 此方法依赖于 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 记录将来可能会改变，只有列出的域名将保持不变。

基本操作所需：

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 包：

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

          **Needed for Git Large File Storage 需要**
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 地址或在企业中实施安全设置策略。