关于自托管运行器

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

本文内容

关于自托管运行器

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

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

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

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

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

如果自托管运行器超过 14 天未连接到 GitHub Actions，则会自动从 GitHub 中删除。如果临时自托管运行器超过 1 天未连接到 GitHub Actions，则会自动从 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 的连接，因此您无需允许 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

用于 Dependabot 更新作业所需

Shell
dependabot-actions.githubapp.com

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

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

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

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

自托管运行器安全

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

GitHub 托管运行器不会出现此问题，因为每个 GitHub 托管运行器始终都是干净的隔离虚拟机，并且会在作业执行结束时被销毁。

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

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

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

限制自托管运行器的使用

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

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