关于自托管运行器

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

托管您自己的运行器

学习路径中的第 1/8 部分
下一步:添加自托管运行器

本文内容

关于自托管运行器

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

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

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

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

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

如果自托管 Runner 未连接到 GitHub Actions 超过 14 天，则会自动从 GitHub 中删除。如果短暂型自托管 Runner 未连接到 GitHub Actions 超过 1 天，则会自动从 GitHub 中删除。

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

GitHub 托管 Runner 和自托管 Runner 之间的区别

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

GitHub 托管 Runner

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

自托管 Runner

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

自托管 Runner 机器要求

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

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

自托管 Runner 的自动缩放

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

使用限制

使用自托管 Runner 时，GitHub Actions 使用有一些限制。这些限制可能会发生变化。

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

自托管 Runner 的工作流连续性

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

自托管 Runner 支持的架构和操作系统

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

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）或更高版本

架构

自托管 Runner 应用程序支持以下处理器架构。

  • x64 - Linux、macOS、Windows。
  • ARM64 - Linux、macOS、Windows（目前处于公开预览阶段）。
  • ARM32 - Linux。

自托管 Runner 与 GitHub 之间的通信

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

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

由于自托管 Runner 会打开与 GitHub 的连接，因此您无需允许 GitHub 向您的自托管 Runner 建立入站连接。

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

您可以使用 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

Runner 版本更新所需

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 地址允许列表，则必须将自托管 Runner 的 IP 地址添加到允许列表。有关更多信息，请参阅 GitHub Enterprise Cloud 文档中的“管理组织的允许 IP 地址”或“实施企业安全设置的策略”。

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

有关排查常见网络连接问题的更多信息，请参阅“监控和排查自托管 Runner”。

自托管 Runner 安全性

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

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

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

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

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

限制自托管运行器的使用

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

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

下一步添加自托管运行器