Mac mini 搭建 GitHub Actions 自託管 Runner 完整指南（生產級 CI 架構｜2026）

什麼是 GitHub Actions 自託管 Runner（Mac mini 版本）

Mac mini GitHub Actions 自託管 Runner 是在 Mac mini 本機或雲 Mac mini 實例上運行 workflow Job 的自託管 CI 執行環境，取代 GitHub 託管的 macOS Runner。

在 Mac mini 上運行 Runner 的五大核心優勢：

• ✔ 建置快取長期保留（DerivedData / CocoaPods / SPM）
• ✔ Xcode 版本完全可控（Golden Image 釘扎）
• ✔ CI 成本固定（不按分鐘計費）
• ✔ iOS 建置速度顯著提升（熱建置可進 5–6 分鐘）
• ✔ 企業級安全隔離（專用 ci 使用者 + Keychain 隔離）

為什麼 iOS CI 必須使用 Mac mini 自託管 Runner

GitHub 託管 Runner 的三大瓶頸

核心結論

GitHub 託管 Runner = 無狀態機器
Mac mini Runner = 有記憶的 CI 系統

這正是 iOS CI 效能差異的本質原因。延伸閱讀：Flutter iOS CI 建置優化：從 28 分鐘到 9 分鐘.

Mac mini CI Runner 生產級三層架構設計

整體架構模型

┌──────────────────────────────┐
│ Layer 1: launchd daemon      │  ← reliability (auto-restart / crash recovery)
├──────────────────────────────┤
│ Layer 2: ci user isolation   │  ← security (Keychain / permission boundary)
├──────────────────────────────┤
│ Layer 3: label routing       │  ← maintainability (workflow → Runner)
└──────────────────────────────┘

第 1 層 — launchd 守護機制（核心穩定性）

launchd = macOS 版 systemd。關鍵能力：自動重啟 Runner、系統重啟自動恢復、崩潰自動拉起、以守護程序級別運行。

關鍵設定三項（缺一不可）：

• RunAtLoad = true — 使用者登入後自動啟動
• KeepAlive = true — 崩潰後自動重拉
• WorkingDirectory — 必須設定（最常見的 Runner 離線根因）

Runner 應使用 LaunchAgents（非 LaunchDaemons），因 iOS CI 需要存取使用者 Keychain 進行程式碼簽章。配合 macOS 自動登入，讓 ci 使用者重啟後自動進入工作階段。

第 2 層 — CI 使用者隔離（安全核心）

為什麼不能用管理員帳號？

• 可以 sudo → 攻擊面無限擴大
• Keychain 可被讀取 → 憑證可能外洩
• fork PR 可執行惡意腳本 → 全機淪陷

推薦方案：專用 ci 使用者

• ❌ 無 sudo 權限，不在管理員群組
• ✅ 獨立 Keychain（/Users/ci/Library/Keychains/）
• ✅ 加入 _developer 群組（允許 xcodebuild / simctl）

sudo dscl . -create /Users/ci UserShell /bin/zsh
sudo dscl . -create /Users/ci RealName "CI Runner"
sudo dscl . -create /Users/ci UniqueID 505
sudo dscl . -create /Users/ci PrimaryGroupID 20
sudo dscl . -create /Users/ci NFSHomeDirectory /Users/ci
sudo createhomedir -c -u ci
sudo passwd ci
sudo dscl . -append /Groups/_developer GroupMembership ci

第 3 層 — Runner 標籤路由系統（CI 調度核心）

標籤體系 = CI 調度系統。推薦三層結構：

runs-on: [self-hosted, macOS, ARM64, flutter-ios, xcode-16, m4]
           ┌──────────────┐  ┌───────────────────┐  ┌──────────────┐
           │ Platform     │  │ Workload          │  │ Hardware     │
           │ self-hosted  │  │ flutter-ios       │  │ m4, 16gb     │
           │ macOS, ARM64 │  │ xcode-16          │  │ region:tokyo │
           └──────────────┘  └───────────────────┘  └──────────────┘

標籤是「與」關係（AND）；workflow 必須完全匹配；多機同標籤 = 自動負載平衡。

Mac mini Runner 安裝完整流程（生產級）

步驟 1 — 安裝 Runner

# Run as ci user
mkdir -p ~/actions-runner && cd ~/actions-runner
curl -fsSL -O https://github.com/actions/runner/releases/download/v2.316.1/actions-runner-osx-arm64-2.316.1.tar.gz
tar xzf actions-runner-osx-arm64-2.316.1.tar.gz

步驟 2 — 註冊 Runner

./config.sh \
  --url https://github.com/your-org/your-repo \
  --token YOUR_REGISTRATION_TOKEN \
  --name "$(hostname -s)" \
  --labels "self-hosted,macOS,ARM64,flutter-ios,xcode-16,m4,16gb" \
  --work _work \
  --replace \
  --unattended

步驟 3 — launchd 守護設定（關鍵）

儲存至 ~/Library/LaunchAgents/com.kvmboot.github-runner.plist：

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0"><dict>
  <key>Label</key><string>com.kvmboot.github-runner</string>
  <key>ProgramArguments</key>
  <array><string>/Users/ci/actions-runner/run.sh</string></array>
  <key>WorkingDirectory</key><string>/Users/ci/actions-runner</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
  </dict>
  <key>StandardOutPath</key><string>/Users/ci/Library/Logs/github-runner.log</string>
  <key>StandardErrorPath</key><string>/Users/ci/Library/Logs/github-runner.err</string>
</dict></plist>

步驟 4 — 啟動 Runner

launchctl load ~/Library/LaunchAgents/com.kvmboot.github-runner.plist
launchctl list | grep github-runner
tail -f ~/Library/Logs/github-runner.log   # expect: Listening for Jobs

網路與代理（出站白名單）

Runner 必須出站存取：*.github.com、api.github.com、*.actions.githubusercontent.com、objects.githubusercontent.com。代理須在 plist EnvironmentVariables 中注入（不會繼承 shell 的 export https_proxy）。完整 IP 段見 api.github.com/meta.

生產級安全加固

自託管 Runner 最大風險來自公開儲存庫的 fork PR。必須開啟三道防線：

1. 儲存庫級 Runner（禁止組織級）

註冊為儲存庫級 Runner，避免組織級橫向權限擴散——一旦某個儲存庫被攻擊，所有儲存庫的 Keychain 和 Secrets 全部暴露。

2. Fork PR 保護機制

GitHub 儲存庫 → 設定 → Actions → 一般，開啟：

要求批准所有外部協作者的 fork 拉取請求工作流程

確保 fork PR 不會自動在自託管 Runner 上執行。詳見 雲 Mac CI 安全隔離體系.

3. Secrets 隔離

• ❌ 不把 .p12、.env 放在 ci 使用者主目錄
• ❌ 不把 API Key 硬編碼在 workflow 中
• ✅ GitHub Secrets + 執行時注入；憑證走 Fastlane match + Keychain

concurrency:
  group: flutter-ios-${{ github.ref }}
  cancel-in-progress: true

CI 效能優化（iOS / Flutter 場景）

Mac mini 自託管 Runner 提升 iOS CI 優化 效果的關鍵在於本機快取持久化：

快取優化三層

• CocoaPods 快取（~/.cocoapods + ios/Pods）
• DerivedData 快取（-derivedDataPath 固定路徑）
• SPM / Flutter pub 快取

完整快取策略見專題：iOS CI 快取體系設計（DerivedData / CocoaPods / SPM）.

一鍵重建 Runner（災難恢復）

macOS 大版本升級、Golden Image 漂移或安全事件後，用 rebuild_runner.sh 在 5 分鐘內完成重建：

#!/usr/bin/env zsh
set -euo pipefail
CI_USER="ci"
PLIST_DEST="/Users/$CI_USER/Library/LaunchAgents/com.kvmboot.github-runner.plist"

sudo -u "$CI_USER" launchctl unload "$PLIST_DEST" 2>/dev/null || true
sudo -u "$CI_USER" bash -c "cd /Users/$CI_USER/actions-runner && ./config.sh remove --token \$(gh api -X POST /repos/your-org/your-repo/actions/runners/remove-token --jq '.token') 2>/dev/null || true"
sudo -u "$CI_USER" zsh /Users/$CI_USER/scripts/setup_runner.sh
sudo -u "$CI_USER" launchctl load "$PLIST_DEST"
echo "[OK] Runner rebuilt."

驗證 Runner 是否生產就緒（檢查清單）

驗收前確認基礎環境已就緒（雲 Mac 開通驗收清單).

層級 1 — Runner 線上

• ✅ GitHub 介面顯示 閒置（Idle）
• ✅ launchctl list | grep github-runner PID 正常
• ✅ 日誌出現 Listening for Jobs

層級 2 — 空 Job

runs-on: [self-hosted, macOS, flutter-ios]

• ✅ Job 30 秒內被分配（不長時間排隊）
• ✅ 輸出 Runner 名稱與 OS 版本

層級 3 — 工具鏈驗證

xcodebuild -version    # matches Golden Image
flutter --version
pod --version

常見問題（長尾關鍵詞覆蓋）

Mac mini 可以運行 GitHub Actions Runner 嗎？

可以，並且是 iOS CI 最常見的生產方案之一。透過 launchd 守護，Mac mini 可長期穩定運行 GitHub Actions 自託管 Runner（macOS） 環境。

自託管 Runner 比 GitHub 託管 Runner 快多少？

通常 iOS CI 可提升 30%–60% 建置速度，主要來自 CocoaPods 與 DerivedData 快取持久化——GitHub 託管 Runner 每次 Job 都是全新環境，無法保留本機快取。

launchd 和 brew services 有什麼區別？

launchd 是 macOS 系統級守護框架（systemd 等價物）；brew services 只是 launchd 的封裝層，不適合管理非 Homebrew 安裝的 Runner。生產環境應直接撰寫 plist。

Runner 離線了怎麼排查？

按優先順序檢查：

1. launchctl list | grep github-runner — 程序狀態
2. plist 中 WorkingDirectory 是否設定
3. workflow runs-on 標籤是否與 Runner 完全匹配

一台 Mac mini 能跑多少個 Runner？

16GB → 建議 1 個；24GB → 1–2 個（輕量任務）。跑 xcodebuild 時記憶體容易打滿，多實例需配合 concurrency 限制。