Skip to main content

关于 GitHub 托管的运行程序

GitHub 提供托管的虚拟机来运行工作流。 虚拟机包含可供 GitHub Actions 使用的工具、包和设置。

GitHub 托管的运行器概述

运行器是在 GitHub Actions 工作流中执行作业的计算机。 例如,运行器可以在本地克隆存储库,安装测试软件,然后运行评估代码的命令。

GitHub 提供可用于运行作业的运行器,你也可以托管自己的运行器。 每个 GitHub 托管的运行器都是一个新的虚拟机 (VM),由 GitHub 托管,并且预安装了运行器应用程序和其他工具,可用于 Ubuntu Linux、Windows 或 macOS 操作系统。 使用 GitHub 托管的运行器时,设备维护和升级由您负责。

可以选择标准 GitHub 托管的运行器选项之一,或者,如果使用 GitHub Team 或 GitHub Enterprise Cloud 计划,则可以预配具有更多核心或者由 GPU 或 ARM 处理器提供支持的运行器。 这些计算机称为“大型运行器”。 有关详细信息,请参阅“关于较大的运行器”。

使用 GitHub 托管的运行程序需要网络访问,上传和下载速度至少为 70 千位每秒。

使用 GitHub 托管的运行器

若要使用 GitHub 托管的运行器,请创建一个作业,并使用 runs-on 来指定将处理该作业的运行器类型,例如 ubuntu-latestwindows-latestmacos-latest。 有关运行器类型的完整列表,请参阅“关于 GitHub 托管的运行程序”。 如果对存储库具有 repo: write 访问权限,则可以查看可在存储库的工作流中使用的运行器列表。 有关详细信息,请参阅“查看存储库可用的运行器”。

作业开始时,GitHub 会自动为该作业预配新的 VM。 作业中的所有步骤在该 VM 中执行,让该作业中的步骤使用运行器的文件系统共享信息。 可以直接在 VM 上或 Docker 容器中运行工作流。 作业完成后,VM 会自动解除授权。

下图演示了如何在两个不同的 GitHub 托管的运行器上执行工作流中的两个作业。

包含两个作业的工作流示意图。 一个作业在 Ubuntu 上运行,另一个在 Windows 上运行。

以下示例工作流有两个作业,名为 Run-npm-on-UbuntuRun-PSScriptAnalyzer-on-Windows。 触发此工作流时,GitHub 为每个作业预配新的虚拟机。

  • 名为 Run-npm-on-Ubuntu 的作业在 Linux VM 上执行,因为作业 runs-on: 指定 ubuntu-latest
  • 名为 Run-PSScriptAnalyzer-on-Windows 的作业在 Windows VM 上执行,因为作业 runs-on: 指定 windows-latest
YAML
name: Run commands on different operating systems
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  Run-npm-on-Ubuntu:
    name: Run npm on Ubuntu
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm help

  Run-PSScriptAnalyzer-on-Windows:
    name: Run PSScriptAnalyzer on Windows
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install PSScriptAnalyzer module
        shell: pwsh
        run: |
          Set-PSRepository PSGallery -InstallationPolicy Trusted
          Install-Module PSScriptAnalyzer -ErrorAction Stop
      - name: Get list of rules
        shell: pwsh
        run: |
          Get-ScriptAnalyzerRule

在作业运行时,可以在 GitHub UI 中查看日志和输出:

工作流运行的屏幕截图。 将显示“在 Windows 上运行 PSScriptAnalyzer”作业的步骤。

GitHub Actions 运行器应用程序是开源的。 可以参与 runner 存储库并在其中提交问题。

查看存储库可用的运行器

如果对存储库具有 repo: write 访问权限,则可以查看存储库可用的运行器列表。

  1. 在 GitHub.com 上,导航到存储库的主页。

  2. 在存储库名称下,单击 “操作”。

    “github/docs”存储库的选项卡的屏幕截图。 “操作”选项卡以橙色边框突出显示。

  3. 在左侧边栏中的“管理”部分下,单击“ 运行器”。****

  4. 查看存储库可用的 GitHub 托管运行器列表。

  5. (可选)要复制运行器标签以在工作流中使用,请单击运行器右侧的 ,然后单击“复制标签”。****

注意:**** 企业和组织所有者可以从此页面创建运行器。 若要创建新的运行器,请单击运行器列表右上角的“新建运行器”****,将运行器添加到存储库。

有关详细信息,请参阅 “管理较大的运行器”和 “添加自托管的运行器”。

支持的运行器和硬件资源

GitHub 托管的运行器可用于公共和专用存储库。

GitHub 托管的 Linux 运行器支持 Android SDK 工具的硬件加速,这使得运行 Android 测试的速度更快,而且消耗的分钟数更少。 有关 Android 硬件加速的详细信息,请参阅 Android 开发人员文档中的为 Android Emulator 配置硬件加速

Note

-latest 运行器映像是 GitHub 提供的最新稳定映像,但可能不是操作系统供应商提供的最新版本的操作系统。

警告:beta 版映像和已弃用的映像“按原样提供”、“包含全部错误”且“视可用性情况”提供,不在服务级别协议和保证的涵盖范围之内。 客户支持可能不会涵盖 Beta 版映像。

用于公共存储库的 GitHub 托管的标准运行器

对于公共存储库,使用下表所示工作流标签的作业可在具有关联规范的虚拟机上运行。 可以在公共存储库上免费且无限制地使用这些运行器。

虚拟机 处理器 (CPU) 内存 (RAM) 存储 (SSD) 工作流标签 说明
Linux 4 16 GB 14 GB ubuntu-latestubuntu-24.04 [Beta 版本]、ubuntu-22.04ubuntu-20.04 ubuntu-latest 标签当前使用 Ubuntu 22.04 运行器映像。
Windows 4 16 GB 14 GB windows-latestwindows-2022windows-2019 windows-latest 标签当前使用 Windows Server 2022 运行器映像。
macOS 3 14 GB 14 GB macos-12macos-11 macos-11 标签已弃用,2024 年 6 月 28 日后将不再可用。
macOS 4 14 GB 14 GB macos-13 空值
macOS 3 (M1) 7 GB 14 GB macos-latestmacos-14 macos-latest 标签当前使用 macOS 14 运行器映像。

用于专用存储库的 GitHub 托管的标准运行器

对于专用存储库,使用下表所示工作流标签的作业可在具有关联规范的虚拟机上运行。 这些运行程序使用 GitHub 帐户分配的免费分钟数,然后按每分钟费率收费。 有关详细信息,请参阅“关于 GitHub Actions 的计费”。

虚拟机 处理器 (CPU) 内存 (RAM) 存储 (SSD) 工作流标签 说明
Linux 2 7 GB 14 GB ubuntu-latestubuntu-24.04 [Beta 版本]、ubuntu-22.04ubuntu-20.04 ubuntu-latest 标签当前使用 Ubuntu 22.04 运行器映像。
Windows 2 7 GB 14 GB windows-latestwindows-2022windows-2019 windows-latest 标签当前使用 Windows Server 2022 运行器映像。
macOS 3 14 GB 14 GB macos-12macos-11 macos-11 标签已弃用,2024 年 6 月 28 日后将不再可用。
macOS 4 14 GB 14 GB macos-13 空值
macOS 3 (M1) 7 GB 14 GB macos-latestmacos-14 macos-latest 标签当前使用 macOS 14 运行器映像。

工作流程日志列出用于运行作业的运行器。 有关详细信息,请参阅“查看工作流程运行历史记录”。

arm64 macOS 运行器的限制

  • GitHub 提供的所有操作均与 arm64 GitHub 托管运行器兼容。 但是,社区操作可能与 arm64 不兼容,需要在运行时手动安装。
  • 由于 Apple 虚拟化框架的限制,不支持嵌套虚拟化和金属性能着色器 (MPS)。
  • Azure 专用网络和分配静态 IP 等网络功能目前不适用于 macOS 大型运行器。
  • 没有为 arm64 macOS 运行程序分配静态 UUID/UDID,因为 Apple 不支持此功能。 但是,为 Intel MacOS 运行程序分配了静态 UDID,具体为 4203018E-580F-C1B5-9525-B745CECA79EB。 如果要在计划测试生成的同一 主机上进行生成和签名,则可以使用开发预配配置文件进行签名。 如果需要静态 UDID,可以使用 Intel 运行程序并将其 UDID 添加到 Apple 开发者帐户。

大型运行器

GitHub Team 和 GitHub Enterprise Cloud 计划的客户可以从一系列托管的虚拟机中选择,这些虚拟机比标准 GitHub 托管的运行器拥有更多资源。 这些计算机称为“大型运行器”。 具有以下高级功能:

  • 更多内存、CPU 和磁盘空间
  • 静态 IP 地址
  • Azure 专用网络
  • 分组运行器的能力
  • 自动缩放以支持并发工作流
  • GPU 支持和 ARM 支持的运行器

这些 大型运行器 由 GitHub 托管,并预安装了运行器应用程序和其他工具。

有关详细信息,请参阅“关于较大的运行器”。

支持的软件

GitHub 托管的运行器中包含的软件工具每周更新。 更新过程需要几天时间,整个部署结束后,main 分支上的预装软件列表将进行更新。

预安装的软件

工作流程日志包括指向准确运行器上预安装的工具的链接。 要在工作流日志中查找此信息,请扩展 Set up job 部分。 在该部分下,展开 Runner Image 部分。 Included Software 后面的链接将说明运行器上运行该工作流的预安装工具。

有关详细信息,请参阅“查看工作流程运行历史记录”。 请参阅运行器映射存储库的可用映像文档,查看每个运行器操作系统包含工具的完整列表。

GitHub 托管的运行器除了上述参考中列出的包之外,还包括操作系统的默认内置工具。 例如,Ubuntu 和 macOS 运行器包括 grepfindwhich 以及其他默认工具。

还可以查看每个版本的 Windows 和 Ubuntu 运行器映像的软件物料清单 (SBOM)。 有关详细信息,请参阅“GitHub Actions 的安全强化”。

使用预安装的软件

我们建议使用操作来与运行器上安装的软件进行交互。 此方法具有以下几个优点:

  • 通常,操作提供更灵活的功能,如版本选择、传递参数的能力和参数
  • 它可确保工作流程中使用的工具版本无论软件更新如何,都将保持不变

如果想要请求工具,请在操作/运行器映像中提出问题。 此仓库还包含有关运行器上所有主要软件更新的公告。

安装其他软件

您可以在 GitHub 托管的运行器上安装其他软件。 有关详细信息,请参阅“自定义 GitHub 托管的运行器”。

GitHub 托管的运行器使用的云主机

GitHub 在 Microsoft Azure 中安装了 GitHub Actions 运行器应用程序的 虚拟机上托管 Linux 和 Windows 运行器。 GitHub 托管的运行器应用程序是 Azure Pipelines Agent 的复刻。 入站 ICMP 数据包被阻止用于所有 Azure 虚拟机,因此 ping 或 traceroute 命令可能无效。 GitHub 在 Azure 数据中心托管 macOS 运行器。

对于 Linux 和 Windows 运行器,GitHub 使用 Dadsv5-series 虚拟机。 有关详细信息,请参阅 Microsoft Azure 文档中的“Dasv5 和 Dadsv5 系列”。

工作流连续性

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

此外,如果工作流程运行已成功排队,但未在 45 分钟内由 GitHub 托管的运行器处理,则会丢弃排队的工作流程运行。

管理权限

Linux 和 macOS 虚拟机都使用无密码的 sudo 运行。 在需要比当前用户更多的权限才能执行命令或安装工具时,你可以使用无需提供密码的 sudo。 有关详细信息,请参阅“Sudo 手册”。

Windows 虚拟机配置为以禁用了用户帐户控制 (UAC) 的管理员身份运行。 有关详细信息,请参阅 Windows 文档中的“用户帐户控制工作原理”。

IP 地址

要获取 GitHub Actions 用于 GitHub 托管运行器的 IP 地址范围列表,您可以使用 GitHub REST API。 有关详细信息,请参阅 GET /meta 终结点响应中的 actions 密钥。 有关详细信息,请参阅“元数据的 REST API 终结点”。

Windows 和 Ubuntu 运行程序托管在 Azure 中,随后具有与 Azure 数据中心相同的 IP 地址范围。 macOS 运行器托管在 GitHub 自己的 macOS 云中。

由于 GitHub 托管的运行器的 IP 地址范围太多,因此我们不建议你将这些范围用作内部资源的允许列表。 相反,建议将 大型运行器 用于静态 IP 地址范围或自托管运行器。 有关详细信息,请参阅“关于较大的运行器”或“关于自托管运行程序”。

API 返回的 GitHub Actions IP 地址列表每周更新一次。

GitHub 托管运行器和 GitHub

的通信要求

GitHub 托管的运行器必须与 GitHub 拥有的端点建立连接才能执行必要的通信操作。 此外,运行器可能需要访问在操作中指定或使用的其他网络。

为确保 GitHub 托管的运行器在配置中的不同网络之间进行适当的通信,请确保已允许以下通信。

Note

列出的一些域名使用 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 包:

Shell
*.pkg.github.com
ghcr.io

Needed for Git Large File Storage 需要

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

etc/hosts 文件

GitHub 托管的运行器预配有 etc/hosts 文件,可阻止对各种加密货币挖掘池和恶意站点的网络访问。 MiningMadness.com 和 cpu-pool.com 等主机会重新路由到 localhost,因此它们不会带来重大安全风险。

文件系统

GitHub 在虚拟机上的特定目录中执行操作和 shell 命令。 虚拟机上的文件路径不是静态的。 使用 GitHub 提供的环境变量为 homeworkspaceworkflow 目录构造文件路径。

目录环境变量说明
homeHOME包含用户相关的数据。 例如,此目录可能包含登录凭据。
workspaceGITHUB_WORKSPACE在此目录中执行操作和 shell 命令。 操作可以修改此目录的内容,后续操作可以访问这些修改。
workflow/event.jsonGITHUB_EVENT_PATH触发工作流的 Webhook 事件的有效负载 POST。 每当操作执行时,GitHub 都会重写此变量,以隔离操作之间的文件内容。

有关 GitHub 为每个工作流创建的环境变量列表,请参阅“变量”。

Docker 容器文件系统

在 Docker 容器中运行的操作在 /github 路径下有静态目录。 但强烈建议使用默认环境变量在 Docker 容器中构建文件路径。

GitHub 保留 /github 路径前缀,并为操作创建三个目录。

  • /github/home
  • /github/workspace - 注意: GitHub Actions 必须由默认 Docker 用户 (root) 运行。 确保 Dockerfile 没有设置 USER 指令,否则你将无法访问 GITHUB_WORKSPACE
  • /github/workflow

延伸阅读