GitHub Actions Mac 运行器

自托管运行器的工作原理

GitHub Actions 运行器是运行在 Mac 上的一个小程序，通过出站 HTTPS 向 GitHub 轮询任务。当工作流需要匹配的标签时，GitHub 把任务交给你的运行器，运行器在工作目录中检出代码并执行各个步骤。无需开放任何入站端口。

运行器可以注册到单个仓库、组织（通过运行器组供多个仓库共用）或企业。对团队来说，组织级运行器通常最实用。

价格为每台机器起始配置的美元月费。需要更多内存、存储或多台机器？联系我们。

注册运行器

1. 订购 Mac，等访问信息出现在“My Macs”后，通过 SSH 连接。
2. 安装 Xcode 和工作流所需的工具。多版本 Xcode 和缓存配置见 Xcode 构建服务器指南。
3. 在 GitHub 中打开仓库或组织，进入 Settings → Actions → Runners → New self-hosted runner，选择 macOS 和 ARM64 架构。
4. 以专用 CI 用户登录，执行 GitHub 页面显示的命令。注册令牌有效期很短，请立即使用。

mkdir ~/actions-runner && cd ~/actions-runner
# paste the curl download and tar commands shown on the GitHub page (osx-arm64)
./config.sh --url https://github.com/your-org/your-repo \
  --token YOUR_REGISTRATION_TOKEN \
  --name hatmac-m6 --labels xcode,m6 --unattended

完整参数请参阅 GitHub 的自托管运行器文档。

作为服务运行

run.sh 适合测试，但会话结束后就会停止。用自带脚本把运行器安装为 launchd 服务：

./svc.sh install
./svc.sh start
./svc.sh status

在 macOS 上，svc.sh 会为配置运行器的用户安装一个 launch agent，因此该用户的会话需要保持运行。日志写在 ~/Library/Logs/actions.runner.*。如需更新或移除运行器，先停止服务，执行 ./svc.sh uninstall，再执行 ./config.sh remove --token ...。

标签与 runs-on

每个自托管运行器都有默认标签 self-hosted、macOS 和 ARM64。你可以添加描述能力的自定义标签，例如 Xcode 版本或机器规格，然后在 runs-on 中指定。只有具备全部所列标签的运行器才会接到该任务。

jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64, xcode]
    steps:
      - uses: actions/checkout@v5
      - run: xcodebuild -version
      - run: xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17'

标签应描述能力而不是机器名，这样以后加第二台 Mac 时不用逐个修改工作流。多台机器的方案见 Mac 构建农场页面。

临时运行器还是持久运行器

	持久	临时（ephemeral）
生命周期	保持注册，持续接任务	只接一个任务，随后注销
缓存	DerivedData、依赖包和工具保持热缓存	除非放在工作目录之外，否则会丢失
隔离	之前任务的残留会保留	更干净，但 Mac 本身仍被复用
适合	私有仓库、可信贡献者	更严格的隔离、自动伸缩脚本

临时运行器使用 --ephemeral 注册，通常由包装脚本在每个任务结束后重新注册：

./config.sh --url https://github.com/your-org --token YOUR_TOKEN --ephemeral --unattended
./run.sh

在独享的物理 Mac 上，大多数团队选择持久运行器，因为热缓存正是提速的关键。

公开仓库的安全提示

GitHub 建议只在私有仓库中使用自托管运行器。在公开仓库里，任何人都能从 fork 发起拉取请求，工作流可能会在你的 Mac 上运行他们的代码。如果一定要用于公开仓库，请要求外部贡献者的工作流经过审批，绝不在运行器上执行 fork 的拉取请求，并让这些任务接触不到机密。无论哪种情况，都应以非管理员用户运行服务，并把签名材料放在独立的钥匙串中。

想了解各 CI 系统的整体方案，请看 macOS CI/CD 运行器概览，或阅读分步文章在云端 Mac mini 上做 iOS CI/CD。

常见问题

GitHub Actions Mac 运行器需要开放入站端口吗？

不需要。运行器通过 HTTPS 主动连接 GitHub 并等待任务。你只需要 SSH 或远程桌面用于自己的管理。

一台 Mac 可以运行多个 GitHub Actions 运行器吗？

可以。每个运行器放在独立目录并使用不同名称。Xcode 构建很占内存，16GB 机型建议只跑一个，两个运行器建议 24GB 或以上。

自托管运行器会消耗 GitHub Actions 分钟数吗？

自托管运行器不消耗托管运行器分钟数，但 GitHub 对自托管运行器的计费规则曾有调整，请以 GitHub 当前价格页面为准。Hatmac 对 Mac 按月固定收费。

应该从哪个方案开始？

Mac mini M6 24GB / 512GB 是最受欢迎的 CI 方案，能放下两个 Xcode 版本和热缓存。详见价格。