GitHub Actions macOS Job 一直卡在 Queued（不是 Xcode 慢）| 排隊診斷

VPSSpark CI 排隊診斷標準（Cloud Mac CI 系列 #2）。閱讀順序：Hook → 主公式 → 症狀 → Failure Model → Hard Rules → Runbook → FAQ。延伸：#1 容量 · #5 擴員 · #3 自託管算账 · #8 構建提速。

1 · Hook：反直覺結論

99% 的 macOS CI queued 問題，不是資源不足，而是 L2（Archive）被錯誤放進 PR 路徑。

2 · 核心：唯一主公式

全文只認下面這一條，其餘章節都是它的展開。

主公式

CI queue problem  ⇔  wait time  >>  run time

工程結論： macOS runner queued = Runner pool 飽和，而不是 build 變慢。

公式不成立 → 非本篇，轉系列 #8。成立 → 對號入座 Failure 3 Layer Model，並落實 CI Hard Rules。

3 · 症狀：Queued ≠ Running

GitHub Actions 裡，Queued 表示 Job 已進 workflow，但尚未拿到 Runner 槽位；In progress 之後才是 xcodebuild、簽名。許多 iOS 團隊把「PR 紅了 1 小時」當成編譯慢——打開時間軸才發現：52 分鐘在等，真正 run 只有 11 分鐘。

誤判代價：升級 Xcode、加 timeout-minutes、加購 minutes 包——Queued 時間往往不計入你以為的構建超時。

度量見 Job 執行時間（queue_wait_seconds vs run duration）。

52 min

wait time

11 min

run time

Queued

≠ In progress

	wait time	run time
介面	Queued	In progress
瓶頸	GitHub Actions macOS runner queue / self-hosted runner queue	Xcode · 簽名 · 上傳
誤操作	加 minutes · 換 Xcode	加快取（→ #8）

4 · 解釋：CI Queue Failure 3 Layer Model

當 wait time >> run time 成立，主因落在下面三層之一（SRE 命名）。

Layer	含義	典型信號	當天動作
Capacity Limit	平台 · `macos-latest`	僅託管 macOS runner queued；minutes ≠ concurrency	減 fanout；Archive 遷出託管 → #3
Pool Misdesign	架構 · self-hosted pool	Archive 進 PR；fast/archive 未分離	落實 Hard Rules → #1 #6
Trigger Explosion	負載 · workflow fanout	matrix / paths；Job 數 > Runner 數	收緊觸發器 → #5

Capacity Limit — 託管 macOS Runner 撞 macOS concurrency cap。Pool Misdesign — 多數主因：Job tier L2 誤入 PR。Trigger Explosion — 修法在 YAML。（Failure Layer ≠ Job 層級 L0/L1/L2。）

5 · 解決：CI Hard Rules（MUST NOT violate）

工程規範語言，三條不可協商。

CI Hard Rules

Rule 1: PR MUST NOT run L2
                Rule 2: L2 MUST run on isolated pool  (macos-archive)
                Rule 3: fast pool MUST remain unblocked  (fast ≠ archive)

                PR     → L0 + L1 only     → macos-fast
                main   → L2 only            → macos-archive

層級	內容	池	Rules
L0	單模組編譯、靜態檢查	`macos-fast`	Rule 1
L1	PR 整合、模擬器測試	`macos-fast`	Rule 1 · MUST NOT Archive
L2	Archive、TestFlight	`macos-archive`	Rule 2+3

圖 1 · Pool Misdesign：L2 占槽 → 全線 queued

PR 觸發 6 個 macOS Job

L2 Archive 38 min

L0/L1 全部 Queued

Runner 拓撲：彈性池 vs 常駐 · #1 容量 · queue 止血後 → #3。

6 · Runbook：一頁紙（on-call）

CI Queue Diagnosis · Standard Path

0. wait >> run ?  ─No→ #8
                1. Capacity | Pool Misdesign | Trigger Explosion
                2. MUST: Rule1-3
                3. PR 無 archive/export ?
                4. wait P95 < 8min → #3

一句話： 99% macOS CI queued 是 L2 誤入 PR，不是機器不夠。 先 wait >> run，再 Failure Model，再 Hard Rules。

7 · FAQ

為什麼 macOS runner 更容易 queued？

Capacity Limit + Pool Misdesign。先 wait >> run。

排隊還是編譯慢？

CI queue problem ⇔ wait time >> run time。

自託管為何也 queued？

Pool Misdesign；違反 Hard Rules。

minutes 與 concurrency？

minutes 計費；concurrency 占槽。加 minutes 不解 queued。

是否 pool 問題？

見 Runbook。

queue 正常但 build 慢？

#8 · #1 · #5。

系列導航（#2）

#1 容量 · #2 本篇 · #3 自託管 · #4–#8 見英文系列表