关于自托管运行器

您可以托管自己的运行器并自定义用于在 GitHub Actions 工作流程中运行作业的环境。

本文内容

关于自托管运行器

自托管运行器是您部署和管理的系统，用于在 GitHub.com 上执行来自 GitHub Actions 的作业。有关 GitHub Actions 的更多信息，请参阅“了解 GitHub Actions”。

与 GitHub 托管运行器相比，自托管运行器可以更好地控制硬件、操作系统和软件工具。使用自托管运行器，您可以创建满足您需求的自定义硬件配置，例如具有处理能力或内存来运行更大的作业，安装本地网络上可用的软件，以及选择 GitHub 托管运行器未提供的操作系统。自托管运行器可以是物理的、虚拟的、容器化的、本地部署的或云端的。

您可以在管理层次结构的不同级别添加自托管运行器

  • 存储库级运行器专用于单个存储库。
  • 组织级运行器可以处理组织中多个存储库的作业。
  • 企业级运行器可以分配给企业帐户中的多个组织。

您的运行器机器使用 GitHub Actions 自托管运行器应用程序连接到 GitHub。GitHub Actions 运行器应用程序是开源的。您可以在 runner 存储库中贡献和提交问题。当发布新版本时，运行器应用程序会在将作业分配给运行器时自动更新自身，或者如果运行器未分配任何作业，则在发布后一周内自动更新自身。

如果自托管运行器未连接到 GitHub Actions 超过 14 天，它将自动从 GitHub 中删除。如果短暂的自托管运行器未连接到 GitHub Actions 超过 1 天，它将自动从 GitHub 中删除。

有关安装和使用自托管运行器的更多信息，请参阅“添加自托管运行器”和“在工作流程中使用自托管运行器”。

GitHub 托管运行器和自托管运行器之间的区别

GitHub 托管运行器提供了一种更快、更简单的运行工作流的方式，而自托管运行器则是一种高度可配置的方式，可以在您自己的自定义环境中运行工作流。

GitHub 托管运行器

  • 自动接收操作系统、预安装的软件包和工具以及自托管运行器应用程序的更新。
  • 由 GitHub 管理和维护。
  • 为每次作业执行提供一个干净的实例。
  • 使用您 GitHub 计划中的免费分钟数，超过免费分钟数后将按分钟收费。

自托管运行器

  • 仅接收自托管运行器应用程序的自动更新，但您可以禁用运行器的自动更新。有关控制自托管运行器上的运行器软件更新的更多信息，请参阅 "使用自托管运行器进行自动扩展"。您负责更新操作系统和所有其他软件。
  • 可以使用您已经付费的云服务或本地机器。
  • 可根据您的硬件、操作系统、软件和安全要求进行自定义。
  • 不需要为每次作业执行提供一个干净的实例。
  • 可免费与 GitHub Actions 一起使用，但您需要负责维护运行器机器的成本。

自托管运行器机器的要求

只要满足以下要求，您就可以使用任何机器作为自托管运行器。

  • 您可以在机器上安装和运行自托管运行器应用程序。有关更多信息，请参阅 "自托管运行器的支持架构和操作系统"。
  • 机器可以与 GitHub Actions 通信。有关更多信息，请参阅 "自托管运行器与 GitHub 之间的通信"。
  • 机器拥有足够的硬件资源来运行您计划运行的工作流类型。自托管运行器应用程序本身只需要最少的资源。
  • 如果您想运行使用 Docker 容器操作或服务容器的工作流，则必须使用 Linux 机器，并且必须安装 Docker。

自托管运行器的自动扩展

您可以根据收到的 Webhook 事件自动增加或减少环境中的自托管运行器数量。有关更多信息，请参阅“使用自托管运行器进行自动缩放”。

使用限制

使用自托管运行器时，GitHub Actions 使用存在一些限制。这些限制可能会发生变化。

  • 作业执行时间 - 工作流中的每个作业最多可以运行 5 天。如果作业达到此限制，则作业将终止并无法完成。
  • 工作流运行时间 - 每个工作流运行限制为 35 天。如果工作流运行达到此限制，则工作流运行将被取消。此时间段包括执行持续时间以及等待和批准所花费的时间。
  • 作业排队时间 - 每个自托管运行器的作业在排队至少 24 小时后将被取消。实际排队时间在取消发生之前可能达到 48 小时。如果自托管运行器在此限制内未开始执行作业，则作业将终止并无法完成。
  • API 请求 - 您可以在一个小时内对存储库中的所有操作执行最多 1,000 个 GitHub API 请求。如果请求超过限制，则其他 API 调用将失败，这可能会导致作业失败。
  • 作业矩阵 - 作业矩阵每个工作流运行最多可以生成 256 个作业。此限制适用于 GitHub 托管运行器和自托管运行器。
  • 工作流运行队列 - 每个存储库在 10 秒间隔内最多可以排队 500 个工作流运行。如果工作流运行达到此限制，则工作流运行将终止并无法完成。
  • 注册自托管运行器 - 一个运行器组最多可以拥有 10,000 个自托管运行器。如果达到此限制，则无法添加新的运行器。

自托管运行器的持续工作流

如果 GitHub Actions 服务暂时不可用，则在触发后 30 分钟内未排队的运行将被丢弃。例如，如果工作流被触发，而 GitHub Actions 服务在 31 分钟或更长时间内不可用，则工作流运行将不会被处理。

自托管运行器支持的架构和操作系统

以下操作系统支持自托管运行器应用程序。

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 之间的通信

自托管运行器连接到 GitHub 以接收作业分配并下载运行器应用程序的新版本。自托管运行器使用 HTTPS 长轮询，它打开与 GitHub 的连接 50 秒，如果未收到响应，则超时并创建新的长轮询。应用程序必须在机器上运行才能接受和运行 GitHub Actions 作业。

自托管运行器与 GitHub 之间的连接通过 HTTPS（端口 443）。

由于自托管运行器打开与 GitHub.com 的连接，因此您无需允许 GitHub 对您的自托管运行器进行入站连接。

您必须确保机器具有适当的网络访问权限，上传和下载速度至少为每秒 70 千比特，才能与下面列出的 GitHub 主机通信。某些主机是基本运行器操作所必需的，而其他主机仅在某些功能需要时才需要。

您可以使用 REST API 获取有关 GitHub 的元信息，包括 GitHub 服务的 IP 地址。有关使用的域和 IP 地址的更多信息，请参阅“用于元数据的 REST API 端点”。

注意

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

基本操作所需

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

用于下载操作

Shell
codeload.github.com
ghcr.io
*.actions.githubusercontent.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
ghcr.io

用于 Git 大文件存储

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

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

如果您对 GitHub 组织或企业帐户使用 IP 地址允许列表，则必须将您的自托管运行器的 IP 地址添加到允许列表中。有关更多信息，请参阅“管理组织的允许 IP 地址”或“执行企业安全设置策略”在 GitHub Enterprise Cloud 文档中。

您也可以将自托管运行器与代理服务器一起使用。有关更多信息，请参阅“将代理服务器与自托管运行器一起使用”。

有关解决常见网络连接问题的更多信息，请参阅“监控和故障排除自托管运行器”。

自托管运行器安全

我们建议您仅将自托管运行器与私有存储库一起使用。这是因为您的公共存储库的分支可以通过创建执行工作流中代码的拉取请求，在您的自托管运行器机器上运行危险代码。

这对于 GitHub 托管运行器来说不是问题，因为每个 GitHub 托管运行器始终是一个干净的隔离虚拟机，并且在作业执行结束时会被销毁。

在您的自托管运行器上运行的不可信工作流会对您的机器和网络环境构成重大安全风险，尤其是在您的机器在作业之间保留其环境的情况下。一些风险包括

  • 机器上运行的恶意程序。
  • 逃离机器的运行器沙箱。
  • 公开访问机器的网络环境。
  • 在机器上持久保存不需要或危险的数据。

有关自托管运行器安全加固的更多信息，请参阅“GitHub Actions 安全加固”。

限制自托管运行器的使用

组织所有者可以选择允许哪些仓库创建仓库级自托管运行器。

有关更多信息，请参阅“为您的组织禁用或限制 GitHub Actions”。