Platform teams running self-hosted macOS runners see the same failure mode: innocent retries hide real product bugs, burn Apple Silicon hours, and train developers to distrust CI. This playbook defines how to classify flakes, when to auto-rerun versus block merges, and how to implement streak-based quarantine on dedicated Mac mini M4 machines—with two decision tables and a six-step rollout you can copy into GitHub Actions or any runner orchestrator.
If you already split UI work across machines, pair this policy withiOS UI test sharding on Mac mini M4so shard skew does not masquerade as test flakiness. For runner installation baselines, start fromself-hosted GitHub Actions on cloud Macand keep Xcode builds identical across the fleet.
無制限の再試行が Mac ビルド フリートの信頼を損なう理由 __分割__ macOS CI は、Linux コンテナとは異なる点でステートフルです。キーチェーン アイテム、シミュレーター キャッシュ、画面ロック、Apple 公証デーモンはすべて、測定するまではランダムに見える障害モードを導入します。書面による再試行予算がないと、オンコール エンジニアは赤の後のすべての緑を「自動的に修正された」と解釈してしまい、マージ リスクが静かに増加します。 __分割__ 指標盲目: __分割__ ワークフローごとの合格/不合格のみを追跡するチームでは、テストが失敗したかどうかを判断できません。 __分割__ 経済的な抵抗: __分割__ プル リクエストごとに 2 回再試行する単一の不安定な UI スイートは、 __分割__ 製品コードが安定している場合でも、週ごとの Mac ランナー分は 1 分です。 __分割__ 誤った学習: __分割__ 開発者は、マージ ゲートが保護する必要がある正確な信号をバイパスして、「グリーンになるまで」ローカルでジョブの再実行を開始します。 __分割__ 障害の指紋: インフラストラクチャ、テスト、それとも製品? __分割__ クォータを変更する前に、ダッシュボードが信号とノイズを分類できるように、フィンガープリントで障害にタグを付けます。以下の表は会話のきっかけとなるものです。「最初のアクション」列をコンプライアンス ルールに合わせて調整してください。 __分割__ 指紋 __分割__ ドライバーの可能性が高い __分割__ 最初のアクション
macOS CI is stateful in ways Linux containers are not: Keychain items, simulator caches, screen locks, and Apple-notary daemons all introduce failure modes that look random until you measure them. Without a written retry budget, on-call engineers interpret every green-after-red as “fixed itself,” which silently increases merge risk.
- Metric blindness:Teams that only track pass/fail per workflow cannot tell whether a test failed onthree different runners or the same overheating host three times.
- Economic drag:A single flaky UI suite that retries twice per pull request can consume20–35%of weekly Mac runner minutes even when product code is stable.
- False learning:Developers begin rerunning jobs locally “until green,” bypassing the exact signal your merge gate should protect.
Failure Fingerprints: Infrastructure, Test, or Product?
Before changing quotas, tag failures with a fingerprint so dashboards sort signal from noise. The table below is a conversation starter—tune the “first action” column to your compliance rules.
| Fingerprint | Likely driver | First action |
|---|---|---|
| 同じランナーのホスト名、さまざまなテスト __分割__ ディスク、温度、または USB ハブの不安定性 __分割__ ジョブを排出します。 SMART と空き領域を検査します (< __分割__ 無料で即時クリーンアップがトリガーされます） __分割__ 同じテスト、どのランナーでも __分割__ テストは壁時計、アニメーション、またはロケールを想定しています __分割__ 検疫チケットを開きます。再試行の上限 __分割__ Xcode バンプ後のスパイク __分割__ ツールチェーンまたはシミュレーターの回帰 __分割__ SDK をピン留めします。フリートの展開前に 1 台のゴールデン Mac で Canary スイートを実行する __分割__ フォークからの pull_request の場合のみ __分割__ シークレットの可用性またはサンドボックスの違い __分割__ ワークフローを分割します。フォークジョブではプロダクション署名ラベルを再利用しないでください __分割__ チームの成熟度ごとの再試行予算と隔離のしきい値 | Disk, thermal, or USB hub instability | Drain jobs; inspect SMART and free space (<15%free triggers immediate cleanup) |
| Same test, any runner | Test assumes wall-clock, animation, or locale | Open quarantine ticket; cap retries at1 until fixed |
| Spike after Xcode bump | Toolchain or simulator regression | Pin SDK; run canary suite on one golden Mac before fleet rollout |
| Only on pull_request from forks | Secret availability or sandbox differences | Split workflows; never reuse production signing labels on fork jobs |
Retry Budget and Quarantine Thresholds by Team Maturity
成熟したチームは、再試行を利息付きのローンとして扱います。以下のマトリックスは、3 つのポリシー プリセットを操作ノブにマッピングします。リポジトリ層ごとに 1 つのプロファイルを選択します。 __分割__ ポリシーノブ __分割__ スターター __分割__ バランスの取れた __分割__ エンタープライズ __分割__ ジョブごとの自動再試行 __分割__ (インフラエラーのみ) __分割__ 入力されたエラー許可リストあり __分割__ フレークストリークを隔離 __分割__ 夜間レポート __分割__ 隔離されたテストのマージ ルール __分割__ 警告バッジ __分割__ 所有者の承認があれば省略可能 __分割__ VPAT 例外を除いてハードブロック
| Policy knob | Starter | Balanced | Enterprise |
|---|---|---|---|
| Auto-retries per job | 2 | 1(infra errors only) | 0–1with typed error allow-list |
| Flake streak to quarantine | Nightly report | 3 fails in 24 h | 2 fails on main |
| Merge rule for quarantined tests | Warning badge | Optional skip with owner approval | Hard block unless VPAT exception |
| ランナーテレメトリ保持 __分割__ 日数 + SIEM エクスポート __分割__ 監査メモ: __分割__ 隔離によってテストがスキップされる場合、コミット SHA、アクター、およびチケット ID をワークフロー ログに保存します。規制当局や料金を支払っている顧客は、偶発的なグリーンビルドではなく、チェック漏れが意識的に行われたことの証拠をますます求めています。 __分割__ Cloud Mac Runner でストリークベースの隔離を展開するための 6 つのステップ __分割__ これらの手順は、メンテナンスのためにホストに SSH 接続できることを前提としています。接続の健全性とアカウントの設定については、 __分割__ 構造化されたランナー ファクトを出力します。 __分割__ 追加 __分割__ 、OS ビルド、Xcode ビルド、および空きディスク GB をすべてのジョブの概要に追加します。 __分割__ 再試行を分類します。 __分割__ 区別する __分割__ (タイムアウト、シミュレータ起動) から __分割__ (アサーションの失敗)。 __分割__ テストごとのストリークを追跡します。 | 7 days | 30 days | 90days + SIEM export |
Audit note:When quarantine skips a test, store the commit SHA, actor, and ticket ID in the workflow log. Regulators and paying customers increasingly ask for proof that skipped checks were conscious—not accidental green builds.
Six Steps to Roll Out Streak-Based Quarantine on Cloud Mac Runners
These steps assume you can SSH to hosts for maintenance. Connection hygiene and account setup are documented in ourhelp center.
- Emit structured runner facts:Add
RUNNER_NAME, OS build, Xcode build, and free-disk GB into every job summary. - Classify retries:Distinguish
infra_retry(timeouts, simulator boot) fromtest_retry(assertion failures). - Track per-test streaks:カウントは小規模なデータベースまたはオブジェクト ストアに保持されます。ストリークをリセットするのは次の場合のみです
__分割__
ワイヤーマージゲート:
__分割__
メンテナー ラベルが存在しない限り、ストリークが階層のしきい値を超えた場合はブロックします。
__分割__
悪いアクターをローテーションする:
__分割__
ホスト名が表示される場合は、
__分割__
毎週レビューします:
__分割__
会議時間の上限を
__分割__
次回のインシデントレビューの前にエクスポートするメトリクス
__分割__
経営陣はグリーンパーセンテージを求めます。信頼性エンジニアにはディストリビューションが必要です。次の集計をウェアハウスに書き込むジョブを毎週スケジュールして、隔離に関する決定が政治的ではなくデータに基づいて行われるようにします。これらのメトリクスをランナーのホスト名および Xcode ビルド ID と関連付けると、通常、開発者がチケットをオープンするずっと前に、単一の不良ノードが明らかになります。
__分割__
再試行調整後の期間:
__分割__
すべての試行を含む実時間。初回試行期間と比較して、再試行税を定量化します。
__分割__
断続性指数:
__分割__
新しいコミットなしで赤から緑に切り替わったジョブの数。これを以下に進めることを目指してください
__分割__
スプリントあたりの macOS ジョブの数。10 consecutive greens on
main. - Wire merge gates:Block when streak exceeds your tier threshold unless a maintainer label is present.
- Rotate bad actors:If a hostname appears in40% of infra retries in a week, pull it from service and reimage.
- Review weekly:Cap meeting time to25 minutes with a dashboard that lists top flake contributors and recovered tests.
Metrics to Export Before Your Next Incident Review
Executives ask for green percentages; reliability engineers need distributions. Schedule a weekly job that writes the following aggregates to your warehouse so quarantine decisions stay data-driven instead of political. Correlating these metrics with runner hostname and Xcode build ID usually exposes a single bad node long before developers open tickets.
- Retry-adjusted duration:Wall-clock time including all attempts; compare against first-attempt duration to quantify retry tax.
- Intermittency index:Count of jobs that flipped from red to green without a new commit; aim to drive this below5%of macOS jobs per sprint.
- 隔離バックログの経過期間: __分割__ スキップされた各テストが最後にメインブランチの実行に成功してからの日数。より古いものはエスカレートする __分割__ シミュレーターブート p95: __分割__ テスト本体とは別に追跡します。起動時間の増加により、SMART アラートが発生する前にストレージ障害が予測されることがよくあります。 __分割__ シークレットスコープの失敗: __分割__ 認証エラーを個別に追跡することで、構成ミスによる無駄な再試行を回避します __分割__ デプロイメント イベントの隣にメトリクスが存在する場合、どの Mac が特定のアーティファクトに触れたか、どの Xcode バージョンがスパイク中にライブであったか、再試行によって回帰が隠蔽されたかどうかなど、監査の質問に数分で答えることができます。 __分割__ 。顧客契約に社内開発者プラットフォームの稼働時間条項が含まれている場合、このナラティブは生の合格率と同じくらい重要です。 __分割__ よくある質問 __分割__ フォークされたプル リクエストでは、リリース ビルドと同じ Mac ラベルを使用する必要がありますか? __分割__ 署名可能なラベルを信頼できないコード パスと共有しないでください。フォークを信頼できないテナントのように扱います。別個のランナー プール、別個のシークレット スコープ、およびより狭い再試行バジェットにより、悪意のあるワークフローがインフラストラクチャを調査できなくなります。 __分割__ 地理は剥離率とどのように影響するのでしょうか? __分割__ ネットワーク依存のテスト (プッシュ通知、CDN エッジ ケース) は、ユーザーに最も近いリージョンで実行する必要があります。 NodeMac は香港、日本、韓国、シンガポール、米国でノードを提供しています。各地域に毎月カナリア ジョブを配置して、DNS または TLS ドリフトがすべての開発者に影響を与える前にキャッチします。 __分割__ 隔離されたスイートに隔離されたランナーを追加する準備ができたら、比較します。Days since each skipped test last had a successful main-branch run; escalate anything older than14 days.
- Simulator boot p95:Track separately from test bodies—rising boot times often predict storage failure before SMART alerts fire.
- Secret-scoped failures:Track authentication errors separately so you do not waste retries on misconfigured
APP_STORE_CONNECTkeys.
When metrics live next to deployment events, you can answer audit questions in minutes: which Mac touched a given artifact, which Xcode versions were live during a spike, and whether retries masked a regression onmain. That narrative is as important as the raw pass rate when your customer contracts include uptime clauses for internal developer platforms.
FAQ
Should forked pull requests use the same Mac labels as release builds?
Never share signing-capable labels with untrusted code paths. Treat forks like untrusted tenants: separate runner pools, separate secrets scopes, and narrower retry budgets so malicious workflows cannot probe your infrastructure.
How does geography interact with flake rates?
Network-dependent tests (push notifications, CDN edge cases) should run in the region closest to your users. NodeMac offers nodes in Hong Kong, Japan, Korea, Singapore, and the United States—place canary jobs in each region monthly to catch DNS or TLS drift before it hits every developer.
When you are ready to add isolated runners for quarantined suites, compareNodeMacの価格 __分割__ チームのレビュー時間を偽りの赤点に費やすコストと比較してください。 __分割__ Mac mini M4 ハードウェアは、Xcode オーケストレーションのための高速シングルスレッド パフォーマンスと、プル リクエスト バーストの間にランナーが座っているときの効率的なアイドル電力を兼ね備えているため、このプレイブックに適合します。 NodeMac の消耗品 __分割__ 専用の物理 Mac mini __分割__ オーバーサブスクライブされた VM ではないマシンで SSH と VNC の両方を使用できるため、デスク マシンと同じ方法でスタックしたシミュレーターをデバッグできます。香港、東京、ソウル、シンガポール、または米国でレンタルすると、不安定な UI の再現をアプリが実際に見るネットワーク条件と同じ場所に配置できると同時に、Mac の 2 番目の「隔離専用」クローゼットに対する前払いの設備投資を回避できます。 __分割__ 隔離に優しい Mac ランナーたちを立ち上がれ __分割__ 香港、日本、韓国、シンガポール、米国に専用の Mac mini M4 ノードを追加し、コンパイルと UI のラベル プールを追加し、実際のバグを隠すことによる無限の再試行を停止します。 __分割__ 価格を見る __分割__ ランナーセットアップヘルプagainst the cost of burning your team’s review hours on false reds.
Mac mini M4 hardware fits this playbook because Apple Silicon combines fast single-thread performance for Xcode orchestration with efficient idle power when runners sit between pull-request bursts. NodeMac suppliesdedicated physical Mac minimachines—not oversubscribed VMs—with both SSH and VNC so you can debug stuck simulators the same way you would on a desk machine. Renting in Hong Kong, Tokyo, Seoul, Singapore, or the United States lets you colocate flaky UI reproduction with the network conditions your app actually sees, while avoiding upfront CapEx for a second “quarantine-only” closet of Macs.