自托管运行程序参考

自托管运行器机器的要求

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

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

支持的处理器体系结构

        `x64` - Linux、macOS、Windows。

```
          `ARM64` - Linux、macOS。
```
```
        `ARM32` - Linux。
```

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

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

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

自动缩放

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

数据变量.product.prodname_actions_runner_controller %}

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

有关 workflow_job webhook 的详细信息，请参阅 Webhook 事件和有效负载。
要了解如何使用 Webhook，请参阅“Webhooks 文档”。

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

身份验证要求

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

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

对于专用存储库，请使用设有repo范围的访问令牌。
对于公共存储库，请使用设有public_repo范围的访问令牌。
对于组织，请使用设有admin:org范围的访问令牌。

要使用 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

github.com
api.github.com
codeload.github.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

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

注意

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

在本文中