プラットフォームチームは Archive をすでに緑にしているのに、公証（Notarization） や stapler で夜を潰すことがあります。キーチェーンのダイアログ、ポーリングのタイムアウト、同一リモート Mac 上で複数ジョブが一時パスを奪い合う、といった事象です。本文は macOS を 専用ビルドプレーン とみなすエンジニア向けで、無人公証の背後にある隠れた前提を炙り出すチェック項目が七つ、配布チャネル別に staple が必須かどうかを示すマトリクス、そして API キー、notarytool submit/store、ログ保持、再試行と並列の境界を含む 六段階の Runbook を提示します。Fastlane と CI、再現可能ビルドとキーチェーン の各記事と役割分担で読み進めてください。
Apple の公証の説明は直線的ですが、長寿命の CI ユーザー と 共有 NVMe の上では失敗が断続的に見え、再現が難しく、ログも分散します。以下の七項目は「たぶん自動化できる」から「変更チケットに書ける」へリスクを移します。
公証を Archive の付録とみなす： notarytool の終了コード処理と成果物保持を切り出さないと、インシデントは「最後に触った人」に戻ります。リリース監査モデルとフィールドを揃えてください。
個人の Apple ID と CI 用 API キーを混在させる： セッション型の資格情報は無人環境で脆いです。2026 年は App Store Connect API キー を既定にし、ヘッドレス Fastlane の秘密情報契約と一致させます。
stapler の意味を無視する： すべてのパイプラインで staple すると壁時計時間と失敗面が増えます。次節のマトリクスに沿って直接ダウンロード、企業ポータル、TestFlight のみなどに分岐します。
複数ジョブが既定の一時領域を共有する： /var/folders や即席 zip ワークスペースの衝突でアップロード破損やハッシュ変化が起きます。DerivedData と同様に パイプライン単位でバケット化 してください。
Apple 側キューへの線形再試行： サービスが混雑しているとき素朴なループは同一 submission を叩き続けます。指数バックオフ、壁時計の上限、チケットシステムへの submission id 記録を使います。
キーチェーンと TCC をデスクトップユーザー並みに設定する： 無人ビルドには専用ログインセッションか明示的な CI キーチェーン分割が必要です。再現可能ビルド のキーチェーン契約と同時にレビューします。
公証失敗サンプルライブラリがない： 緑のときだけログを読むチームは Invalid や Hardened Runtime の退行でバージョン三元組やスクショが不足します。ナレッジベースに取得テンプレートを固定します。
共通の根は、リモート Mac を「Xcode が動く Linux」とみなし、公証の状態機とキーチェーン境界 を持つ専用ノードとして扱わないことです。エンタープライズビルドプール とセットで、多数のアプリがフリートを共有するときは公証の並列度と署名の隔離をプラットフォーム SLA に書き、アプリごとのリポジトリ任せにしないでください。
素の xcodebuild と比べ、公証フェーズは 可観測性と冪等性 を強調します。同一バイナリの再提出、リクエスト識別子まわりの冪等意味論、インシデントに紐づく再生可能なシェルコマンドです。この三つを Runbook に落とすことで「コンパイルできる」から「署名・公証・監査できる」へ進みます。
夜間 Archive と日中 PR が同一ホストを奪い合うなら、公証ジョブをコンパイル偏重ジョブから分離します。公証はネットワーク揺らぎと Apple 側キューに敏感で、CPU 拘束ビルドと混ぜると尾部遅延が膨らみます。GitLab の resource_group や Actions の並列上限と同型で、リソース名は人が読める「notarization slot」にします。
プロバイダが 固定の外向き IP やリージョン選択を提供する場合は、RTT と TLS 中間者ポリシーを受け入れ試験に織り込みます。Apple 宛トラフィックを復号する企業プロキシは「コンパイルは緑、公証は赤」の典型原因です。
運用の成熟度には Xcode とともに notarytool CLI を版管理することも含まれます。Apple は Xcode とコマンドラインツールで更新を出すため、社内変更ログに挙動を固定するとイメージ更新後のフラグ変更サプライズを避けられます。API キーはローテーションし、どの issuer がどのチームかを文書化してインシデント対応で p8 を当てずっぽうにしないでください。
最後に、公証テレメトリをコンパイル時間と同じダッシュボードへ接続します。提出時間、ポーリング回数、staple 時間、ディスク空き率を一次級数列として追跡すれば、全リリースブランチで公証を有効化したあと「CI が遅くなった」と聞かれたときに容量計画を正直に説明できます。
一枚の表ですべての組織を閉じられませんが、ユーザーがバイナリをどう受け取るか を軸にするとレビューが速くなり、受け入れ基準もテスト可能になります。
| 観点 | 直接 .dmg/.zip | 企業ポータル | TestFlight / App Store |
|---|---|---|---|
| 公証提出 | 多くの場合必須：既定パスで Gatekeeper が検証可能なチケットを要求 | 必須：MDM やポータルの署名方針に整合 | Apple ホスト配布が主：ローカル stapler の期待は直接ダウンロードと異なる |
| stapler staple | 強く推奨：オフラインインストールでチケットをバンドル内に同梱 | ポータルが再 zip するか次第：再パッケージは再公証か方針変更を要することがある | 「ローカルビルドのたびに staple」と同義ではない：リリースチャネルに従う |
| 失敗の波及 | ユーザー向け隔離プロンプトとサポート負荷 | コンプライアンス項目とセキュリティインシデントレビューの可能性 | 多くはアップロードや処理キューとして現れ、CI 公証と同型ではない |
| リモート Mac 上の利点 | 専用ディスクと安定した外向き通信：notary zip とログを残しやすい | 社内アーティファクトストアと同居すると転送時間を短縮 | Fastlane に引き渡し：公証とアップロード役を分離 |
| よくある誤解 | 「Accepted」ならダブルクリック必ず成功とみなし staple のタイミングを落とす | アンチウイルスがペイロードを書き換えチケットを無効化 | デスクトップの notarytool 感覚を App Store Connect の処理遅延に当てはめる |
公証の文脈で「VPS のように Mac を借りる」とは、再現可能な提出プレーン を買うことです。固定ユーザー、予測可能なディスク余裕、ワークトラッカーで submission id をビルド指紋に結びつける状態機を備えます。
notarytool と非推奨パスを対比するときは メンテナンスウィンドウ を定義します。GUI セッションに依存するスクリプトが残るか、すべての呼び出し元が JSON と構造化ログを出すか。「完了」は一時的に緑の単一リポジトリではなく、CI テンプレートと社内足場をフリート全体で更新した状態です。
マルチリージョンでも各ノードの外向き経路とプロキシ方針を文書化します。アップロードの地理的近接はコンパイルほど重要ではありませんが、「東京でビルドしシリコンバレーで公証」の経路をデータ取り扱いメモなしにするとコンプライアンス上驚きが出ます。
セキュリティレビュー資料には一枚の決定記録を添付します。選んだチャネル、staple の有無、API キーローテの責任者、クリーン VM でチケットを検証するコマンドです。スクショ単体より長持ちします。
順序は まず身元と鍵、次に成果物と提出、最後に並列 を強調します。再現可能ビルド の指紋スクリプトと揃え、提出だけでなく事後検証も可能にします。
専用 CI ユーザーとログイン基線を作る： 個人の Apple ID と共有しない。長いポーリングを妨げない画面ロック方針を確認する。
API キーと notarytool 資格情報を配置する： p8、Issuer ID、Key ID の三つ組。ファイルは CI ユーザーに読み取り専用。p8 を平文でリポジトリに入れない。
パイプライン内でアップロード可能な成果物を作る： .app を正しく署名し zip/dmg 化。パスにパイプライン id を埋め、SHA256 をビルドログへ出す。
submit し submission id を捕捉する： --wait か独自ポーリング。Apple の状態オブジェクトを成果物ディレクトリに残す。
ログを保存し失敗を分類する： Invalid では詳細ログを取得。チケットで xcodebuild -version と git commit を関連付ける。
配布方針に従い staple して検証する： ポータルやオブジェクトストアへ載せる前に stapler validate とクリーン VM 上のインストール行列を実行する。
ZIP_PATH="dist/MyApp.${CI_PIPELINE_ID}.zip"
xcrun notarytool submit "$ZIP_PATH" \
--key "./AuthKey_XXXXX.p8" \
--key-id "$ASC_KEY_ID" \
--issuer "$ASC_ISSUER_ID" \
--wait \
--output-format json > "logs/notary-${CI_PIPELINE_ID}.json"
# 失敗時は詳細を取得（json から submission id を解析）
# xcrun notarytool log <submission-id> --key ... > "logs/notary-detail.txt"
xcrun stapler staple "dist/MyApp.app"
ヒント： 同一パイプラインが App Store Connect へもアップロードする場合は Fastlane と CI の引き渡し を読み、API キーの役割（Developer と App Manager）と notarytool の最小権限を変数表に書き、万能鍵を避けてください。
Xcode や macOS の大規模アップグレード日には、まず最小の署名バンドルで カナリア公証 を行い notarytool と stapler を端到端で検証してからアプリケーションリポジトリを開放します。ゴールデンイメージのロールバックと補完関係にあります。
プロバイダがスナップショットを提供するなら、スナップショットに 公証ツールチェーンの版 をタグします。Xcode のビルド番号、CLI ツール版、既知の notarytool 挙動変更です。チーム全体で「謎の既定フラグ」退行を追わなくて済みます。
成果物保持はコンプライアンスと結びつけます。notary JSON と stapler 出力を数か月保持しなければならないチームもあります。オブジェクトストアの IPA 横に置くか、ライフサイクル付きの監査バケットに置くか早期に決めてください。
よくある誤りは「同時に何本の xcodebuild が入るか」を公証にそのまま写すことです。実際には アップロード帯域、Apple 側キュー、zip の CPU、そして キーチェーンのロック解除 がフェーズごとに支配します。
notary_slots を明示的に定義します。例としてリモート Mac あたり同時 submit は最大 1〜2、残りはキュー待ち。壁時計のタイムアウトと許容キュー SLA を文書化します。SwiftPM と CocoaPods のディスク管理 と交差します。公証用の一時 zip は大きく、DerivedData と別ボリュームか別ディレクトリに置き、夜間バッチでシステムディスクを埋めないでください。
注意： ディスクが安全閾値を下回ったまま公証ジョブを押し込まないでください。半端に書かれた zip は再現しにくい形でアップロードに失敗します。スケジューリングを止め、監査可能な削除リストで掃除してから再開します。
再試行方針を分けます。ネットワーク瞬断 には短い上限付き再試行、Apple 側の混雑 には分単位のバックオフと上限を使い、レート制限を踏まないようにします。すべての再試行で submission id と成果物ハッシュをログし、「世代違いの staple」事故を防ぎます。
集中プロキシは Apple エンドポイントの明示許可リストと TLS バイパス規則が必要です。さもなくばコンパイルはすべて緑、公証はすべて赤で、証拠はプロキシ機器にしか残りません。
ノートパソコンの偶発 Archive と比べ、専用リモート Mac は 24/7 で予測可能な環境と固定の SSH 運用面 を買います。プラットフォームは公証 Runbook、ディスク水位、鍵ローテを同一ノードプロファイルに束ねられ、開発者各端末がバラバラに漂うのを避けられます。
自己修復エージェントを導入するときは進行中の notary ワークスペースを消さないでください。リースやパイプライン認識パスで削除ジョブを守り、自動化が stapler ステップと競走しないようにします。
以下は社内合意用です。閾値はバンドルサイズと並列度に合わせて調整してください。比率は一般的なプラットフォーム慣行を反映しており、SLA を固める前に自環境で再測定してください。
--wait に 明示的上限とアラート を付けます。submission id、成果物 SHA256、xcodebuild -version を同一成果物バンドルに残し、チーム横断で再生可能にします。オフィスのノート PC はスリープ方針、VPN の揺らぎ、個人キーチェーンに悩まされます。純粋な Linux は Apple の署名チェーンをホストできません。作業を 専用で常時オンかつ SSH 到達可能 なリモート Mac に移し、notarytool と stapler をテンプレ化すると「ビルドを出せる」から「証明でき監査でき引き渡せる」へ進みます。場当たりの予備機材や不透明な仮想化スタックは一貫した SSH、明瞭なディスク段、再現可能なノードプロファイルを欠きがちで統制が苦しくなります。安定した iOS CI/CD と AI エージェント自動化には、これらの運用プリミティブを一つの提供形にまとめた NodeMini のクラウド Mac Mini レンタル がしばしばより適合します。仕様と料金は 料金ページ を参照し、オンボーディングは ヘルプセンター で完了させてください。
本 Runbook を社内リリース段階に結び付けます。ホットフィックス、ステージング、本番レーンで公証の並列度、ログ保持、staple 検証行列を変えても、パイプライン全体を分岐させずに済ませられます。
Apple は API キーに基づく notarytool を推奨しています。JSON 出力、スクリプト可能なポーリング、明瞭なエラーはリモート Mac 上の対話的 Apple ID セッションより CI に適します。ノードサイジングでは 料金ページ を参照してください。
チャネル依存です。直接ダウンロードではオフラインの Gatekeeper 検査のために staple が要ることが多いです。App Store と TestFlight は Apple のホストチェーンに従います。ネットワークとアクセスは ヘルプセンター を参照してください。
一時ディレクトリの競合、レート制限、キーチェーンの混線です。notary_slots を抑え、ワークディレクトリをバケット化し、再現可能ビルド および エンタープライズビルドプール のキーチェーン契約と一致させてください。