关于自托管运行器

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

托管您自己的运行器

学习路径中的 8 个中的 1 个
下一步：添加自托管运行器

本文内容

关于自托管运行器

自托管运行器是您部署和管理的系统，用于在 GitHub.com 上执行来自 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.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 地址添加到允许列表中。有关更多信息，请参阅 GitHub Enterprise Cloud 文档中的“管理组织的允许 IP 地址”或“执行企业安全设置策略”。

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

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

自托管运行器安全

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

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

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

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

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

限制自托管运行器的使用

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

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

下一步添加自托管运行器