GitHub 托管运行器的概述
运行器是在 GitHub Actions 工作流中执行作业的机器。例如,运行器可以克隆您的本地仓库,安装测试软件,然后运行评估代码的命令。
GitHub 提供您可以用来运行作业的运行器,或者您可以自托管运行器。每个 GitHub 托管运行器都是 GitHub 托管的一个新的虚拟机 (VM),预安装了运行器应用程序和其他工具,并提供 Ubuntu Linux、Windows 或 macOS 操作系统。当您使用 GitHub 托管运行器时,机器维护和升级将由 GitHub 代为处理。
您可以选择标准的 GitHub 托管运行器选项之一,或者如果您使用的是 GitHub Team 或 GitHub Enterprise Cloud 计划,您可以配置具有更多内核的运行器,或者由 GPU 或 ARM 处理器驱动的运行器。这些机器被称为“大型运行器”。更多信息,请参阅“关于大型运行器”。
使用 GitHub 托管运行器需要网络访问,上传和下载速度至少为每秒 70 千比特。
使用 GitHub 托管运行器
要使用 GitHub 托管的运行器,请创建一个作业,并使用runs-on
指定将处理该作业的运行器类型,例如ubuntu-latest
、windows-latest
或macos-latest
。有关运行器类型的完整列表,请参阅“关于 GitHub 托管的运行器”。如果您对某个仓库具有repo: write
访问权限,则可以查看该仓库中工作流可用的运行器列表。更多信息,请参阅“查看仓库可用的运行器”。
作业开始时,GitHub 会自动为此作业准备一个新的虚拟机。作业中的所有步骤都在虚拟机上执行,允许该作业中的步骤使用运行器的文件系统共享信息。您可以直接在虚拟机上或在 Docker 容器中运行工作流。作业完成后,虚拟机将自动取消分配。
下图演示了工作流中的两个作业如何在两个不同的 GitHub 托管运行器上执行。
以下示例工作流包含两个作业,名为Run-npm-on-Ubuntu
和Run-PSScriptAnalyzer-on-Windows
。触发此工作流时,GitHub 将为每个作业准备一个新的虚拟机。
- 名为
Run-npm-on-Ubuntu
的作业在 Linux 虚拟机上执行,因为该作业的runs-on:
指定了ubuntu-latest
。 - 名为
Run-PSScriptAnalyzer-on-Windows
的作业在 Windows 虚拟机上执行,因为该作业的runs-on:
指定了windows-latest
。
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
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 中查看日志和输出。
GitHub Actions 运行器应用程序是开源的。您可以在runner仓库中贡献和提交问题。
查看仓库可用的运行器
如果您对某个仓库具有repo: write
访问权限,则可以查看该仓库可用的运行器列表。
-
在 GitHub 上,导航到仓库的主页。
-
在您的仓库名称下,单击 Actions.
-
在左侧边栏的“管理”部分下,单击 运行器.
-
查看仓库可用的 GitHub 托管运行器列表。
-
可选:要复制运行器的标签以便在工作流中使用,请单击运行器的右侧,然后单击**复制标签**。
支持的运行器和硬件资源
GitHub 托管的运行器可用于公共和私有仓库。
GitHub 托管的 Linux 运行器支持 Android SDK 工具的硬件加速,这使得运行 Android 测试更快,并消耗更少的分钟数。有关 Android 硬件加速的更多信息,请参阅 Android 开发者文档中的配置 Android 模拟器的硬件加速。
注意
-latest
运行器镜像是 GitHub 提供的最新稳定镜像,可能不是操作系统供应商提供的最新操作系统版本。
警告
Beta 版和已弃用的镜像按“现状”、“包含所有缺陷”和“按可用性”提供,不包含在服务等级协议和保修中。Beta 版镜像可能不受客户支持的涵盖。
公共仓库的标准 GitHub 托管运行器
对于公共仓库,使用下表中所示工作流标签的作业将在具有关联规格的虚拟机上运行。在公共仓库上使用这些运行器是免费且不受限制的。
虚拟机 | 处理器 (CPU) | 内存 (RAM) | 存储 (SSD) | 工作流标签 |
---|---|---|---|---|
Linux | 4 | 16 GB | 14 GB |
ubuntu-latest 、ubuntu-24.04 、ubuntu-22.04 、ubuntu-20.04 |
Windows | 4 | 16 GB | 14 GB |
windows-latest 、windows-2022 、windows-2019 |
macOS | 3 | 14 GB | 14 GB |
macos-12
|
macOS | 4 | 14 GB | 14 GB |
macos-13
|
macOS | 3 (M1) | 7 GB | 14 GB |
macos-latest 、macos-14 、macos-15 [公开预览] |
私有仓库的标准 GitHub 托管运行器
对于私有仓库,使用下表中所示工作流标签的作业将在具有关联规格的虚拟机上运行。这些运行器使用您的 GitHub 帐户分配的免费分钟数,然后按分钟收费。更多信息,请参阅“关于 GitHub Actions 的计费”。
虚拟机 | 处理器 (CPU) | 内存 (RAM) | 存储 (SSD) | 工作流标签 |
---|---|---|---|---|
Linux | 2 | 7 GB | 14 GB |
ubuntu-latest 、ubuntu-24.04 、ubuntu-22.04 、ubuntu-20.04 |
Windows | 2 | 7 GB | 14 GB |
windows-latest 、windows-2022 、windows-2019 |
macOS | 3 | 14 GB | 14 GB |
macos-12
|
macOS | 4 | 14 GB | 14 GB |
macos-13
|
macOS | 3 (M1) | 7 GB | 14 GB |
macos-latest 、macos-14 、macos-15 [公开预览] |
工作流日志列出了用于运行作业的运行器。更多信息,请参阅“查看工作流运行历史记录”。
arm64 macOS 运行器的限制
- GitHub 提供的所有操作都与 arm64 GitHub 托管运行器兼容。但是,社区操作可能与 arm64 不兼容,需要在运行时手动安装。
- 由于 Apple 的虚拟化框架的限制,不支持嵌套虚拟化和 Metal Performance Shaders (MPS)。
- Azure 专用网络和分配静态 IP 等网络功能目前不适用于 macOS 大型运行器。
- arm64 macOS 运行器没有分配静态 UUID/UDID,因为 Apple 不支持此功能。但是,Intel MacOS 运行器被分配了一个静态 UDID,具体为
4203018E-580F-C1B5-9525-B745CECA79EB
。如果您在计划测试构建的同一主机上构建和签名,则可以使用开发配置文件进行签名。如果您确实需要静态 UDID,则可以使用 Intel 运行器并将它们的 UDID 添加到您的 Apple Developer 帐户。
大型运行器
GitHub Team 和 GitHub Enterprise Cloud 计划的客户可以选择一系列托管虚拟机,这些虚拟机的资源比标准 GitHub 托管运行器更多。这些机器被称为“大型运行器”。它们提供以下高级功能:
- 更多 RAM、CPU 和磁盘空间
- 静态 IP 地址
- Azure 专用网络
- 分组运行器的能力
- 自动缩放以支持并发工作流
- 支持 GPU 和 ARM 的运行器
这些大型运行器由 GitHub 托管,并预安装了运行器应用程序和其他工具。
更多信息,请参阅“使用大型运行器”。
支持的软件
GitHub 托管运行器中包含的软件工具每周更新一次。更新过程需要几天时间,main
分支上预安装软件的列表在整个部署结束后更新。
预安装的软件
工作流日志包含指向确切运行器上预安装工具的链接。要在工作流日志中查找此信息,请展开“设置作业”部分。在该部分下,展开“运行器镜像”部分。包含的软件
后面的链接将描述运行工作流的运行器上预安装的工具。
更多信息,请参阅“查看工作流运行历史记录”。有关每个运行器操作系统的包含工具的完整列表,请参阅运行器镜像仓库中的可用镜像文档。
除了上述参考资料中列出的软件包外,GitHub 托管的运行器还包括操作系统的默认内置工具。例如,Ubuntu 和 macOS 运行器包含grep
、find
和which
等默认工具。
您还可以查看 Windows 和 Ubuntu 运行器镜像每个版本的软件物料清单 (SBOM)。更多信息,请参阅“GitHub Actions 的安全加固”。
使用预安装的软件
我们建议使用操作来与安装在运行器上的软件交互。这种方法有几个好处:
- 通常,操作提供更灵活的功能,例如版本选择、传递参数和参数的能力。
- 它确保无论软件更新如何,工作流中使用的工具版本都保持不变。
如果您想请求某个工具,请在actions/runner-images中打开一个问题。此仓库还包含有关运行器上所有主要软件更新的公告。
安装其他软件
您可以在 GitHub 托管的运行器上安装其他软件。更多信息,请参阅“自定义 GitHub 托管的运行器”。
GitHub 托管运行器使用的云主机
GitHub 在安装了 GitHub Actions 运行器应用程序的 Microsoft Azure 虚拟机上托管 Linux 和 Windows 运行器。GitHub 托管的运行器应用程序是 Azure Pipelines 代理的一个分支。所有 Azure 虚拟机的入站 ICMP 数据包都被阻止,因此 ping 或 traceroute 命令可能无法工作。GitHub 在 Azure 数据中心托管 macOS 运行器。
对于 Linux 和 Windows 运行器,GitHub 使用Dadsv5-series
虚拟机。更多信息,请参阅 Microsoft Azure 文档中的Dasv5 和 Dadsv5 系列。
GPU 运行器使用NCasT4_v3-series
虚拟机。更多信息,请参阅 Microsoft Azure 文档中的NCasT4_v3 系列。
工作流连续性
如果 GitHub Actions 服务暂时不可用,则如果工作流运行在触发后 30 分钟内未排队,则该运行将被丢弃。例如,如果触发工作流并且 GitHub Actions 服务不可用 31 分钟或更长时间,则工作流运行将不会被处理。
此外,如果工作流运行已成功排队,但未在 45 分钟内由 GitHub 托管的运行器处理,则排队的 workflow 运行将被丢弃。
管理员权限
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 托管运行器在您配置中的网络之间进行正确的通信,请确保允许以下通信。
注意
列出的一些域名使用 CNAME
记录进行配置。某些防火墙可能需要您为所有 CNAME
记录递归添加规则。请注意,CNAME
记录将来可能会更改,只有列出的域名将保持不变。
必要的核心操作
github.com api.github.com *.actions.githubusercontent.com
github.com
api.github.com
*.actions.githubusercontent.com
下载 Actions 所需
codeload.github.com ghcr.io *.actions.githubusercontent.com
codeload.github.com
ghcr.io
*.actions.githubusercontent.com
上传/下载作业摘要、日志、工作流工件和缓存所需
results-receiver.actions.githubusercontent.com *.blob.core.windows.net
results-receiver.actions.githubusercontent.com
*.blob.core.windows.net
运行器版本更新所需
objects.githubusercontent.com objects-origin.githubusercontent.com github-releases.githubusercontent.com github-registry-files.githubusercontent.com
objects.githubusercontent.com
objects-origin.githubusercontent.com
github-releases.githubusercontent.com
github-registry-files.githubusercontent.com
获取 OIDC 令牌所需
*.actions.githubusercontent.com
*.actions.githubusercontent.com
下载或发布包或容器到 GitHub Packages 所需
*.pkg.github.com ghcr.io
*.pkg.github.com
ghcr.io
Git 大型文件存储所需
github-cloud.githubusercontent.com github-cloud.s3.amazonaws.com
github-cloud.githubusercontent.com
github-cloud.s3.amazonaws.com
Dependabot 更新作业所需
dependabot-actions.githubapp.com
dependabot-actions.githubapp.com
etc/hosts
文件
GitHub 托管运行器配置了 etc/hosts
文件,该文件阻止对各种加密货币挖矿池和恶意网站的网络访问。例如 MiningMadness.com 和 cpu-pool.com 等主机被重定向到本地主机,因此不会构成重大的安全风险。
文件系统
GitHub 在虚拟机上的特定目录中执行操作和 shell 命令。虚拟机上的文件路径不是静态的。使用 GitHub 提供的环境变量来构建 home
、workspace
和 workflow
目录的文件路径。
目录 | 环境变量 | 描述 |
---|---|---|
home | HOME | 包含用户相关数据。例如,此目录可能包含登录尝试的凭据。 |
workspace | GITHUB_WORKSPACE | Actions 和 shell 命令在此目录中执行。操作可以修改此目录的内容,后续操作可以访问这些内容。 |
workflow/event.json | GITHUB_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
进一步阅读
- “管理 GitHub Actions 的账单”
- 您可以使用矩阵策略在多个镜像上运行您的作业。更多信息,请参阅“在工作流中运行作业的不同变体”。