闲置 Mac 变身额外 GitHub Actions 算力
macOS CI 突发运行器是一个可选的菜单栏控制器，支持完成当前任务后暂停，并带有磁盘安全防护，让您离开时也能将 Mac 临时用于 CI 任务。
仓库内提供 AI 配置提示说明。

Apache-2.0 开源协议：
https://github.com/TheTom/macos-ci-burst-runner…

TheTom/macos-ci-burst-runner

来源：https://github.com/TheTom/macos-ci-burst-runner

Mac CI 突发运行器

一款可选的菜单栏控制器，仅在您需要时将 Mac 用作 GitHub Actions 自托管运行器。同时兼容 Apple Silicon 和 Intel 芯片 Mac，支持组织级或仓库级运行器配置。

控制器具有四种运行状态：

• 关闭： 运行器服务已停止，调度标签已移除
• 可用： 调度标签已添加，服务在线，连接电源时 Mac 保持唤醒
• 忙碌： GitHub 显示有活跃任务，此时禁止关闭
• 排空： 立即移除调度资格，当前任务可完成，随后停止服务并解除唤醒锁

同时支持配置磁盘剩余空间阈值，在启动前和 GitHub Actions 任务启动钩子中双重验证。

安全第一

自托管运行器在您的 Mac 上执行仓库控制的代码。建议尽可能使用专用 macOS 账户或独立设备。请勿将个人工作站暴露给不受信任的仓库、公开分支的拉取请求或可能被不受信任贡献者修改的工作流。

对于组织运行器，建议创建受限运行器组，仅允许选定的私有仓库访问，并在可用情况下限定受信任的工作流。所有符合条件的工作流必须配置 BURST_LABEL 标签；否则无法通过移除标签安全地停止机器。

本项目不存储任何 GitHub 凭据，而是使用基于 macOS 钥匙串的现有 gh 登录凭证。请勿在 config.env 中存放令牌。

环境要求

• macOS 13 或更高版本
• 支持 Swift 6 的 Xcode 命令行工具
• GitHub CLI（https://cli.github.com/）与 jq 工具
• 需要拥有者/管理员权限以注册和标记所选运行器范围

组织标签管理需要认证身份对自托管运行器具有写入权限。GitHub 在自托管运行器 REST API 文档中详细说明了经典令牌 admin:org 权限要求及细粒度替代方案（https://docs.github.com/en/rest/actions/self-hosted-runners）。

安装配置

1. 无需将令牌复制到本仓库，直接完成认证：

   gh auth login  
   gh auth status  
   

2. 构建并安装菜单控制器：

   ./Scripts/install-controller.sh  
   

   此脚本会将本地文件安装到 ~/Library/Application Support/MacCIBurst，为菜单应用创建登录启动代理，并创建（但不立即加载）在可用状态下使用的 caffeinate 启动代理。

3. 编辑生成的私有配置文件：

   open -e "$HOME/Library/Application Support/MacCIBurst/config.env"  
   

   需设置运行器范围、所有者、名称、唯一突发标签、目录路径、磁盘阈值及可选运行器组。组织级运行器无需配置仓库名称，除非需要在菜单中显示当前任务链接。

4. 在 GitHub 中将组织运行器组限制为选定的受信任私有仓库。GitHub 建议为自托管运行器使用私有仓库，避免公开分支提交危险工作流代码。详见《使用运行器组管理访问权限》（https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/manage-access）。

5. 审核所有目标工作流，必须精确匹配突发标签：

   jobs:  
     test-on-mac:  
       runs-on: [self-hosted, macOS, burst]  
       steps:  
         - uses: actions/checkout@v4  
         - run: ./your-safe-test-command  
   

   组织运行器还支持组与标签组合路由：

   runs-on:  
     group: your-restricted-runner-group  
     labels: burst  
   

6. 注册运行器：

   "$HOME/Library/Application Support/MacCIBurst/bin/setup-runner.sh"  
   

   脚本会自动选择当前 Mac 架构的官方运行器包，经过 SHA-256 校验后安装。注册完成后保持关闭状态，调度标签已移除。

7. 验证初始安全状态：

   "$HOME/Library/Application Support/MacCIBurst/bin/mac-ci-burst" status | jq  
   

8. 建议在正式使用前，使用无害工作流测试完整流程：可用 → 忙碌 → 完成后暂停 → 关闭。

合上 MacBook 盖子通常会触发休眠，即使在 caffeinate 激活状态下。请保持盖子开启，或使用支持的电源闭合模式配置。

命令行控制

mac-ci-burst status       # 输出 JSON 状态（适用于脚本/诊断）  
mac-ci-burst available    # 通过磁盘检测，添加调度资格，启动运行器  
mac-ci-burst drain        # 移除资格，完成当前任务，停止服务  
mac-ci-burst off          # 立即停止（GitHub 显示忙碌时拒绝操作）  
mac-ci-burst reconcile    # 强制执行目标状态与磁盘阈值检查  

安装的命令位于：
~/Library/Application Support/MacCIBurst/bin/mac-ci-burst（除非覆盖 MAC_CI_BURST_HOME 环境变量）

安全模型

唯一突发标签是调度开关。可用状态先添加标签（此时运行器离线），再启动服务；排空操作首先移除标签，确保现有任务完成前不会分配新任务。

这是纵深防御机制，非沙箱隔离。已分配给运行器的工作流将以 macOS 运行器账户权限执行。磁盘检查不能保护凭据、源文件或无关进程。

测试方法

swift build -c release  
./Tests/test-controller.sh  

控制器测试使用模拟的 GitHub、服务、休眠和磁盘命令，从不注册真实运行器或修改 GitHub 状态。

AI 辅助配置

AI_AGENT_SETUP_PROMPT.md 提供了可直接使用的安全提示模板，适用于 AI 编程助手。文档明确了可检查/安装的内容、需要人工决策的事项，以及如何验证运行器处于关闭状态后再完成配置。

许可证

Apache License 2.0，详见 LICENSE 文件。