2026-04-17 リース済み Apple Silicon クラウド Mac 上の iOS dSYM とクラッシュシンボリケーション CI

iOS チームが香港、東京、ソウル、シンガポール、米国東部でヘッドレス Mac mini M4 をリースするとき、ビルドマシンは物語の半分に過ぎません。クラッシュシンボリケーションは、出荷バイナリに埋め込まれた UUID と一致する dSYM バンドルに依存します。この 2026-04-17 ランブックでは、.xcarchive が DWARF をどこに格納するか、CI がホストをローテーションするときに「自分の Mac では動いた」ギャップを避ける方法、xcodebuild archive 後のシンボルアップロード順序、共有ビルダー上の NVMe 現実に合わせた保持設計を整理します。IPA エクスポートと App Store Connect API、シミュレータとアーカイブのディスク掃除、DerivedData の隔離と併読し、各レーンを再現可能に保ってください。加えて、dSYM メタデータ（バージョン、Git SHA、Xcode ビルド、アップロード受領 URL）をリリースチケットへ転記すると、インシデント時の照合が容易になります。

2026 年においても dSYM が勝つ理由

Xcode Organizer、App Store Connect、サードパーティバックエンドに表示されるクラッシュは、最終的に DWARF メタデータでスタックフレームを解決します。リリースパイプラインが誤ってシンボルを剥がしたり、誤った Git コミットをアーカイブしたり、App Store バイナリと異なる最適化レベルの dSYM をアップロードすると、匿名フレームが消えません。リース済みクラウド Mac では失敗モードがさらに悪化します。揮発ディスクが ~/Library/Developer/Xcode/Archives を積極的に削除させ、数週間後にシンボル化スタックを期待する誘惑が生じます。

金融や医療のチームでは「説明可能な事故報告」が求められることがあり、dSYM パッケージがなければスクリーンショットと推測に頼るしかありません。シンボルバンドルを監査証跡の一部として扱い、誰がビルドし、いつどこへアップロードし、どれだけ保持するかをコードレビュー記録と同列に扱ってください。

• UUID の忠実性 — アーキテクチャスライスごとに識別子があり、一度でも一致しないリビルドがバンドル全体を無効化します。
• Bitcode の遺産 — 多くのチームはもはや bitcode を出荷しませんが、古いドキュメントが運用を混乱させます。bcsymbolmaps をまだ生成するパイプラインに限り dSYM + bcsymbolmaps に集中してください。
• マルチアーキテクチャの fat バイナリ — デバイス用とシミュレータ用の dSYM がアップロードスクリプトで取り違えられていないか検証してください。

シンボルファイルは実際どこにあるか

xcodebuild archive の後、Xcode はバイナリとシンボルを単一の .xcarchive バンドル配下にネストします。実務上、アップロードが成功するまでそのディレクトリを不変アーティファクトとして扱うべきです。

同一クラウド Mac で複数アーカイブレーンを並列実行する場合は、各 ARCHIVE_PATH に専用サブディレクトリを割り当て、競合書き込みによる dSYM ディレクトリの半端状態を避けてください。壊れた zip はアップロード段階で初めて顕在化し、調査コストが跳ね上がります。

パス（代表例）	内容	CI メモ
…/dSYMs/*.dSYM	ターゲット単位の DWARF バンドル	決定的な名前で zip：${SCHEME}-${GIT_SHA:0:7}.dSYM.zip
…/Products/Applications/*.app	シンボル剥離済みの release アプリ	dSYM 取得後に再コード署名しない — UUID ドリフトのリスク
BCSymbolMaps（存在する場合）	レガシーのシンボルマップ	ASC アップロードテンプレートが要求する場合に dSYM と同梱

dwarfdump --uuid Your.app/YourBinary

アーカイブ後パイプライン：順序がすべて

1. 入力の凍結 — CURRENT_PROJECT_VERSION、MARKETING_VERSION、Git SHA、Xcode ビルド番号をアーカイブ横の JSON sidecar に記録します。
2. IPA エクスポート（任意レーン） — エクスポートオプションのガイドに従います。一部の method はシンボルアップロードの既定を変えます。
3. dSYM zip のステージング — DerivedData ではなくアーカイブからコピーし、部分的なデバッグマップを避けます。
4. アップロード — アーカイブを削除する前に ASC / Transporter 互換フローまたはサードパーティシンボルエンドポイントへ送ります。
5. 検証 — クラッシュバックエンドまたは ASC の処理状態をポーリングし、確認または SLA タイムアウトまでローカル成果物を刈り取らないでください。

夜間バッチでは「アップロード成功」をハードゲートにし、検証に失敗したビルドを App Store 候補キューへ進めない運用が安全です。

保持マトリクス：ホット、ウォーム、コールド

ティア	期間	場所	根拠
ホット	7〜14 日	ビルダー NVMe	再ダウンロードを高速化し、インシデント橋渡しと緊急再スピンを支える
ウォーム	90 日	オブジェクトストレージ／セカンダリ Mac	多くの App Review と初期採用クラッシュをカバー
コールド	1〜7 年	コンプライアンスアーカイブ	規制産業向け。保存時暗号化とアクセス監査

共有クラウド Mac 上の CI 自動化パターン

/Volumes/ci-artifacts（または NVMe マウント）配下でジョブごとの専用サブディレクトリを使い、並列レーンが dSYM zip を上書きしないようにします。DerivedData をジョブ単位で隔離しているなら、同じ規律を ARCHIVE_PATH にも拡張してください。GitHub Actions や Jenkins の SSH ステップでは、アップロードを指数バックオフ付きリトライで包みましょう。シンガポールのビルダーから米国エンドポイントへのアップロードはピーク時に遅くなりがちです。

アップロードを「圧縮（CPU）—転送（ネットワーク）—検証（API）」の三段に計測すると容量計画が容易になり、圧縮時間がアーカイブ本体に迫るなら専用ワーカーへのオフロードを検討できます。

NVMe 予算とジョブ調整

保持する各 .xcarchive は中規模の SwiftUI アプリで6〜25 GB（dSYM 含む）を消費することが多く、夜間ビルドを掛け合わせると 512 GB を財務が気付く前に使い切ります。別ノードを 料金ページ から増やす前に、掃除ランブック がアップロード検証済みのビルドだけを残すことを確認してください。空き容量 12% 未満は新規アーカイブを一時停止するハードゲートにします。

財務と話す際は「レーンあたりのピーク使用量 × 並列数 × 保持日数」でレンジ提示すると、単なるディスクアラートより承認が得やすいです。

リージョナルビルダー：レイテンシとプライバシー

日本と韓国のチームはテスターに近い場所でアーカイブしつつ、グローバルな ASC 処理を狙うことがあります。問題ありませんが、シンボルアップロードが承認されたリージョンに留まるか、クラッシュベンダーへの転送が暗号化されているかを明確にしてください。第二地理へミラーする場合は、各ミラーが保持する build id を文書化し、重複削除の誤操作を防ぎます。

クロスボーダーチームでは、シンボルがサードパーティ SaaS を経由するか、鍵ローテーションの責任者は誰か、RTO/RPO をアーキテクチャ図に落とし込みましょう。「シンボル可用性」を付帯運用ではなく SLO に含めてください。

関連ランブックと次のステップ

本文を 並列 xcodebuild キュー と並べ、圧縮フェーズでディスクを奪い合わないようにします。インシデント急増時は、自動化エージェントがビルドログ横に診断を吐くなら 構造化ログのパターン と突き合わせてください。dSYM の正しさには直接関係しませんが、「シンボル欠落」チケットと実際のアップロード失敗を相関させるのに役立ちます。

FAQ：クラウド Mac CI における dSYM 規律

質問	実務的な答え
dSYM アップロードは CI で同期すべき？	非同期アップロード + アーカイブ削除前のブロッキング検証を推奨。同期は単純ですがパイプラインを長くします。
dSYM を後から再生成できる？	同一のコンパイラ入力をビット単位で再現できる場合のみ。再生成は最後の手段として扱い、方針にしないでください。
週半ばに Xcode を上げたら？	リリースブランチごとにツールチェーンを凍結。アーカイブと再署名で異なる Xcode マイナーを混ぜるのは UUID 不一致の主要因です。

まとめ：dSYM を領収書のように扱い — 不変、日付付き、監査可能 — アップロードの受領が存在する前に NVMe 圧力で削除しないでください。