为什么 GitHub Actions macOS Job 一直卡在 Queued（不是 Xcode 慢）

VPSSpark CI Queue Diagnosis Standard（Cloud Mac CI 系列 #2）。下文阅读顺序：Hook → 主公式 → 症状 → Failure Model → Hard Rules → Runbook → FAQ。延伸：#1 容量 · #3 自托管算账 · #5 扩员 · #8 构建提速。

1 · Hook：反直觉结论

2 · 核心：唯一主公式

全文只认下面这一条。其余章节都是它的展开。

CI queue problem  ⇔  wait time  >>  run time

3 · 症状：Queued ≠ Running

GitHub Actions 里，Queued 表示 Job 已进 workflow，但还没拿到 Runner 槽位；In progress 之后才是 checkout、xcodebuild、签名。很多 iOS 团队把「PR 红了 1 小时」当成编译慢——打开时间轴才发现：52 分钟在等，真正 run 只有 11 分钟。

这类误判的代价是买错药：升级 Xcode、加 timeout-minutes、加 GitHub 分钟包——Queued 时间往往不计入你以为的构建超时，团队只是在日历上多等一天。

Queued = Job 已进 workflow，尚未拿到 Runner 槽位；In progress 后才是 xcodebuild。实录：wait 52 min · run 11 min——团队误以为是 Xcode 慢。度量见 Job 执行时间（queue_wait_seconds vs run duration）。

4 · 解释：CI Queue Failure 3 Layer Model

当 wait time >> run time 成立，主因落在下面三层之一（SRE 命名，便于写 incident runbook）。

Capacity Limit — 托管 macOS Runner 撞 macOS concurrency cap（limits）。Pool Misdesign — 多数案例主因：Job tier L2 误入 PR、fast/archive 混池。Trigger Explosion — 修法在 YAML，不在加机器。（注：Failure Layer 与下文 Job 层级 L0/L1/L2 是两套命名。）

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

工程规范语言。三条规则不可协商。

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

L0 / L1 / L2 类型参考（服务于 Hard Rules，非第二套模型）：

jobs:
                  pr-fast:
                    if: github.event_name == 'pull_request'
                    runs-on: [self-hosted, macos-fast]
                    # L0 + L1 only

                  release-archive:
                    if: github.ref == 'refs/heads/main' || github.event_name == 'schedule'
                    runs-on: [self-hosted, macos-archive]
                    # L2 only · dedicated pool

Runner 拓扑延伸：弹性池 vs 常驻 · #1 容量 · queue 止血后加机器 → #3。

6 · Runbook：一页纸（可转发 on-call）

0. CI queue problem ⇔ wait time >> run time  ?  ─No→ #8
                1. Failure layer: Capacity | Pool Misdesign | Trigger Explosion
                2. MUST: Rule1 PR no L2 · Rule2 L2 isolated · Rule3 fast unblocked
                3. PR workflow 无 archive/export/upload ？
                4. wait P95 < 8min → 再评估 Runner (#3)

一句话结论： 99% 的 macOS CI queued 问题，不是资源不足，而是 L2 被错误放进 PR 路径。 macOS runner queued = Runner pool 饱和信号；先 wait >> run，再 Failure Model，再 Hard Rules。

7 · FAQ