2026 年在雲 Mac 上部署 GitHub Actions 自建 macOS runner：註冊、鑰匙圈、並行與成本對照

當 iOS 管線每週觸發十幾次 xcodebuild archive，GitHub Actions macOS 託管 runner 的分鐘賬單會先刺痛財務——而平臺工程真正需要的是：一臺角色清晰的 雲 Mac 構建機，上面只跑 自建 macOS runner，鑰匙串與 Derived Data 路徑固定、出口 IP 可審計。 本文只回答「如何在租用 Mac 上落地 GHA self-hosted」，不重複 Windows 上搜 Xcode 的選型（見 虛擬機、雲 Mac 與 CI 怎麼選），也不展開 TestFlight 上傳專機（見 加拿大節點 TestFlight 席位）。

1. 何時該從託管 macOS runner 切到自建

託管 GitHub Actions macOS runner 的優勢是零運維、隊列由 GitHub 調度；隱性成本是：高峯月分鐘數、artifact 保留策略、以及跨洋排障時「只能看摘要日誌」的人力折算。下列信號說明該評估 自建 macOS runner + 雲 Mac 構建機：

• 同一倉庫每月 macOS 作業 > 3,000 分鐘，且大量時間花在 derived data 冷啓動而非編譯。
• 需要固定 hostname / 獨享 IPv4 做 ASC API、Webhook 或企業代理白名單。
• Distribution 證書與 match 必須落在單寫節點，禁止在共享託管池輪換鑰匙串。
• 亞太白天提交、北美夜間批跑——與 公證與 Release 自建流水線 同一臺加拿大席位的銜接需求。

2. 託管分鐘 vs 雲 Mac 專機：成本與可控性對照

粗算：若月均 5,000 macOS 分鐘、單價約 $0.08，則託管側約 $400/月 量級（未計私有倉庫加成）。一臺 M4 24GB/512 雲 Mac 專機在不少供應商處接近或低於該數，且同一臺機還可兼 VNC 驗收與 Fastlane 上傳——這是「雲 Mac 構建機」相對純 CI SaaS 的結構性優勢。

3. 推薦架構：labels、併發與「單寫」邊界

不要把「編譯」「簽名」「上傳 ASC」混在同一 workflow 的同一 job 裏搶鑰匙串。2026 年更穩的分工：

• runner 標籤：macos-m4-canada（地理）、signing（僅 match）、build（允許並行 2 若 24GB+）。
• 併發：簽名 job concurrency: signing 全局 1；編譯 job 可按分支併發 2，避免 Derived Data 鎖死。
• 跨區：亞太 runner 只做 lint/unit；加拿大 雲 Mac 構建機 承接 archive + exportArchive。

4. 在雲 Mac 上註冊 runner（首臺）

在 GitHub → Settings → Actions → Runners → New self-hosted runner → macOS，複製註冊命令。SSH 登錄雲 Mac 後建議用專用系統用戶（如 runner），與交互式 VNC 管理員分離。

# 以 runner 用戶登錄雲 Mac
mkdir -p ~/actions-runner && cd ~/actions-runner
curl -o actions-runner-osx-arm64.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.319.1/actions-runner-osx-arm64-2.319.1.tar.gz
tar xzf actions-runner-osx-arm64.tar.gz
./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO \
  --token YOUR_TOKEN --labels macos-m4-canada,arm64 --unattended
sudo ./svc.sh install
sudo ./svc.sh start
./run.sh --check

驗證：在倉庫放一個僅跑 sw_vers && xcodebuild -version 的 workflow，runs-on: [self-hosted, macos-m4-canada]。通過後 pin Xcode：sudo xcode-select -s /Applications/Xcode_16.3.app 並寫入倉庫 README。

5. 鑰匙串、match 與無人值守解鎖

自建 runner 失敗 Top3 之一是「codesign 找不到 identity」。在雲 Mac 上：

1. 導入 Distribution 證書到 login 鑰匙串，設置 ACL 允許 codesign / security。
2. match 倉庫單獨 job，concurrency: signing；其他 job 只讀 ~/Library/MobileDevice/Provisioning Profiles。
3. 用 security set-key-partition-list 處理 CI 解鎖（僅限受控構建機，禁止複製到開發者筆電）。
4. 在 workflow 裏顯式 KEYCHAIN_PATH，避免 GHA 默認臨時鑰匙串覆蓋 match 結果。

jobs:
  archive:
    runs-on: [self-hosted, macos-m4-canada, build]
    steps:
      - uses: actions/checkout@v4
      - name: Build archive
        run: |
          xcodebuild -scheme MyApp -configuration Release \
            -archivePath $RUNNER_TEMP/MyApp.xcarchive archive

6. 雲 Mac runner 安全加固

自建 runner 會執行倉庫（及配置不當時的 fork）任意腳本。請把雲 Mac 構建機當作生產簽名堡壘，而非實驗 VM。

• 倉庫範圍：優先組織級 runner + 顯式倉庫白名單；不信任的分支保護下禁止 fork PR 觸發自建機。
• 用戶隔離：服務賬戶用 runner，禁止其 VNC 登錄。
• Secrets：match 密碼與 ASC API Key 放 GitHub Environments 並設審批；季度輪換。
• 網絡：出站放行 GitHub + Apple CDN；入站僅辦公室 IP 或 Tailscale SSH。
• 磁盤加密：雲 Mac 開啓 FileVault；快照導出排除明文 *.p12。

7. 運維：磁盤水位、Xcode 升級與 runner 輪換

Xcode 小版本升級：先 ./svc.sh stop，升級後跑 smoke workflow，再 svc.sh start。runner 軟件大版本（actions-runner 包）建議每月第一個維護窗替換，保留舊目錄回滾。

8. 組織級 runner 與多倉庫策略

平臺團隊很快會從「單倉庫註冊」升級到組織級 runner 分組：

• Runner groups 對應環境（如僅 ios-release 可用 signing 標籤）。
• Ephemeral（若許可）每 job 清盤——適合不可信構建，不適合 match 緩存；簽名機勿開。
• 在 CODEOWNERS 規定哪些倉庫可寫 runs-on: [self-hosted]，防 rogue workflow 成爲主要外泄面。

兩條產品線共用一臺雲 Mac 構建機時，用 labels 分流而非急着買第二臺——直到磁盤黃色告警週週出現。若 Xcode 大版本不兼容，應加席位，勿在同一卷做雙 xcode-select 切換。

9. 可觀測性：失敗 job 要留什麼日誌

託管 runner 隱藏基礎設施；自建必須自建信號。最低配：

1. 紅構建時同步 ~/actions-runner/_diag/Runner_*.log 到日誌棧。
2. 每 5 分鐘 cron：df -h + ./run.sh --check，離線超 10 分鐘告警。
3. Fastlane 輸出標註 run-id，便於對照 ASC 上傳錯誤。
4. 隊列深度 > 3 時先告警平臺頻道，避免開發誤判「GitHub 變慢」。

10. 首周 Runbook 檢查清單

1. 選定一臺 雲 Mac 構建機（建議 24GB/512 起，周更 > 3 次考慮 1TB）。
2. 註冊 runner + labels；倉庫默認 runs-on 仍用託管，僅 Release workflow 切 self-hosted。
3. 跑通 smoke → 空 archive → 帶簽名的 TestFlight 內測分支（可先不上傳）。
4. 記錄月均分鐘：若託管仍 < 1,500 分鐘，可暫不遷移次要倉庫。
5. 文檔化 ASC API Key 與 match 寫權限只在該機。
6. 配置磁盤告警與日誌 ~/actions-runner/_diag 保留 7 天。

14. FAQ

自建 macOS runner 是否違反 GitHub 條款？

官方支持 self-hosted；需自行承擔安全補丁與密鑰保管。不要把 runner 裝在不可信的共享池。

一臺雲 Mac 能掛幾個 runner？

技術上可註冊多個目錄，但 iOS 簽名與磁盤 I/O 建議一臺物理機一個隊列，用 labels 區分 job 類型即可。

ARM64 runner 能編譯 x86_模擬器嗎？

Apple Silicon 原生構建爲主；若必須 x86 模擬器矩陣，單獨加 Intel 雲 Mac 或託管 runner 補矩陣。

和 GitLab macOS runner 比呢？

原理相同：固定 macOS 主機 + agent。本文聚焦 GitHub Actions 生態與 workflow 語法。

私有倉庫 minutes 更貴，自建是否更划算？

當 macOS 作業 > 3,000 分鐘/月或需要固定 IP/鑰匙串時，通常 2–3 個月內專機更可控。

runner 離線怎麼告警？

用 GitHub Enterprise 的 runner 狀態 API，或 cron 跑 ./run.sh --check 配合外部 uptime 探針。

Hashvps 節點適合嗎？

適合需要獨享 IPv4、M4 裸金屬與加拿大/亞太多區選擇的團隊；選型前對照節點延遲文與套餐磁盤檔位。

Derived Data 要不要在自建機上緩存？

要。固定路徑如 /Users/runner/DerivedDataCache，按 Swift 版本 + Package.resolved 哈希分桶；依賴升級時主動失效，可節省 30–50% 增量編譯時間。

12. 三階段從託管分鐘遷到自建

階段 A（第 1 周）：註冊雲 Mac runner，僅 workflow_dispatch 影子跑，對照同 commit 託管 job 耗時，不動簽名。

階段 B（第 2 周）：archive 切 self-hosted；TestFlight 上傳暫留託管或手工，直至鑰匙串連續 5 夜穩定。

階段 C（第 3 周起）：match/簽名遷至 signing 標籤；默認分支關託管 macOS；保留一條 workflow_dispatch 託管災備 job。

13. 12 個月 TCO 試算表（可複製給財務）