2026 Mac クラウド CI での Apple 公証（Notarization）：notarytool、よくある却下理由、ヘッドレス SSH と短時間デスクトップの判断表
xcodebuild archive は Mac クラウドで安定しても、公証で止まるチームは多い。API Key 誤設定、却下ログの読みにくさ、ローカル GUI では通るのに CI だけ失敗、という三類型を Runbook 化する。本稿は失敗タイプの表で切り分け、純 SSH で十分か短時間 VNC が要るかを表で決め、notarytool 送信・ポーリング・stapler・ログ保全までを五段階に整理する。ディスク余白と公証ジョブ並列も数値目安付き。
要点
1. 署名・公証・App Store アップロードを分離する
自己ホスト Mac では Linux VPS 感覚で SSH 管理しがちだが、コード署名、Apple 公証、TestFlight／App Store Connect アップロードは別プロトコル別クレデンシャルである。署名は codesign と Profile／Hardened Runtime、ログは xcodebuild に出る。公証は zip／dmg／pkg を送り、却下は notarytool の JSON や log に出やすい。アップロードは別 API Key とエンドポイントなので Secrets を混ぜると層別トリアージが壊れる。三層をジョブ分割して初めて夜間パイプラインが安定する。
- 署名：Archive／export で失敗、
xcodebuildログが主戦場。 - 公証：提出物を送り、Apple 側スキャン待ち。CLI ログが本体。
- アップロード：Transporter／Fastlane 等。権限セットが公証と一致しない。
この分離は「手元 Mac では通るのに CI だけ落ちる」を減らす最初の一歩になる。
2. CI 公証の失敗タイプ表
ポストモーテムで entitlements を見るべきか、API Key と出口を疑うべきかを即断する。
| 症状 | 想定原因 | 最初の確認 |
|---|---|---|
| 即時認証エラー | Issuer／Key ID 誤り、期限切れ、シークレット改行欠落 | .p8 パス、CI のマルチライン注入 |
| 長時間 In Progress | キュー、巨大パケット、追加ヒューリスティック | submission id 保持、notarytool log、バックオフ延長 |
| Hardened Runtime 系却下 | 未署名ヘルパー、危険な entitlement | codesign --verify --deep、entitlements diff |
| GUI ありローカルのみ成功 | キーチェーン／対話依存 | §3 の表で VNC か人手ゲートを検討 |
3. ヘッドレス SSH と短時間デスクトップ
既定は API Key＋非対話 notarytool。監査性はビルドディレクトリに JSON／テキストを残すのが最も楽。7×24 や多ブランチではヘッドレスが勝ち、例外だけ短いデスクトップ枠を別キューに載せて xcodebuild 高負荷と分離する。launchd で PATH と Xcode 版を固定し、サイレントアップグレードで挙動が変わらないよう CI 側でも版指定する。
| 観点 | ヘッドレス | 短時間 VNC |
|---|---|---|
| 資格情報 | API Key のみ | キーチェーン／GUI 専用ツール |
| 監査 | ログを成果物に同梱しやすい | 録画やダブルチェックが増える |
| 安定運用 | 繰り返し向き | 低頻度例外向き |
4. 五ステップ：submit → poll → staple → 保管 → 巻き戻し
- ツールチェーン固定：イメージ上で
xcodebuild -versionを記録し CI で明示選択。 - 提出物準備：sha256 記録、パス権限、巨大 zip は一時領域を先に確保。
- submit：
notarytool submitの stdout／JSON をartifacts/notary/submit.logに保存。 - poll：
notarytool info等で指数バックオフ。失敗時はnotarytool logを成果物ストアへ添付。 - staple：成功後
xcrun stapler staple。失敗ならリリースを止め、最後の良好 staple 版を保持。
5. ディスク・タイムアウト・並列の目安
Linux 移行チームは tmp とキーチェーンの差を軽視しがちだが、公証はローカル展開と再圧縮で IO が跳ねる。Archive 後でもシステム巻に概ね 25GB 級のピーク余白を見込み、10GB 未満なら新規公証ジョブを拒否し DerivedData や古い ipa を先に掃除する。単一 submission のポール上限はパケットに応じ 45〜90 分でアラート化。同一ホストで複数 notarytool を並列にすると CPU／ディスクが競合するため公証並列は 1〜2 に抑え、重い xcodebuild と時間帯をずらす。notary JSON／テキストは 90 日以上保管し、アップロード用ログとはバケットを分ける。公証専用 API Key をメタデータ変更権限から分離し 90 日ローテを推奨する。
- ディスク：25GB 目安のバッファ、10GB 割れでゲート。
- ポーリング：提出と完了を別 KPI に分ける。
- 並列：公証 1〜2 レーンまで。
6. FAQ
TestFlight より先に公証か？ 一般的には署名と必要な staple を先にし、export 形態に合わせ Runbook に順序を固定。Gatekeeper と ASC の状態ズレを防ぐ。
ネットワーク揺らぎ：HTTPS_PROXY／NO_PROXY を公証ドメインとアップロードドメインで分けて見る。
VNC をゼロにできるか：多くの現行パイプラインで可能。キーチェーン依存は鍵分割と稀な人手ゲートが現実的。
ノート PC 任せはスリープとポリシーで壊れやすく、分課金ホスト Runner は大容量公証＋キュー待ちでコストと再現性に乏しい。Apple ツールチェーンを予測可能に保ち API Key を監査しやすくしたいチームには、専用 Mac クラウドで署名〜公証〜アップロードを載せ替えるのが拡張に有利。VPSMAC の TestFlight 記事と合わせてジョブ境界とシークレットを一度に揃えるとよい。完全な Linux 代替ではないが、iOS／macOS 配布では Apple 実機環境が不可欠であり、長期運用ではレンタブルな Mac ノードの方がハードウェア持ち込みより運用負債が低い場面が多い。