2026 App Store Connect API：Linux に残す処理と SSH Mac クラウドへ寄せる処理（レート制限と再試行）
Linux VPS に慣れたチームほど「HTTP が通れば全部 Ubuntu でよい」と誤解しやすい。2026 年現在、App Store Connect API はメタデータや価格、TestFlight グループ操作を担える一方、xcodebuild archive、署名、notarytool、Xcode 由来の成果物検証は macOS 必須のままだ。本稿は安価な Linux オーケストレーション層と少数の SSH Mac クラウド Runner を組む読者向けに、(1) 三つの誤解、(2) 配置マトリクス、(3) 七ステップ、(4) 429 と並列度のレビュー数値、(5) FAQ、(6) まとめ、を順に示す。TestFlight と API Key 分離の長編とは役割分担する。
1. 三つの誤解：App Store Connect API を「ただのREST」だと思う落とし穴
Linux VPS 文化に慣れたチームほど「JWT が通れば Ubuntu で十分」と誤解しやすい。API はメタデータや TestFlight 操作を担うが、xcodebuild archive、署名、notarytool は macOS 公式ツールに依存する。本稿は誤解三つ、配置表、七ステップ、429 数値、FAQ、まとめの順で整理する。
- バイナリアップロードを単一 REST とみなす：API は状態照会やキュー投入を担えるが、再現性のある署名・ステープル・監査ログは macOS 実行面なしには成立しにくい。Linux だけで「何とかする」経路はスクリプトの闇袋化を招き、インシデント後の説明責任を壊す。
- 指数バックオフだけを増やす：ジョブ単体では親切でも、リポジトリ横断で同期してスロットルを叩くと「雷鳴」になり、全体遅延が悪化する。アプリ ID 単位のグローバルキューが必須。
- キーと Runner ラベルの対応を書かない：Issuer ID・Key ID・
.p8を全チームが共有すると、最小権限の設計が紙空文になる。VPSMAC サイトの TestFlight 記事で扱う match と API Key 分離とセットで読むと理解が早い。
先に「どの処理が純粋 API で、どれが macOS 必須か」を表に落とし、429 の扱いはその後でよい。
2. 配置マトリクス：メタデータ、照会、成果物
初回アーキレビュー向けに、作業負荷と推奨ホスト、リスクを一枚にまとめる。
| 作業 | 推奨 | 備考 |
|---|---|---|
| バージョン列挙、ローカライズ読取、価格読取 | Linux でも Mac でも可 | ETag キャッシュと読み取り爆増に注意 |
| Beta グループ、テスター割当、ビルド紐付けの書込 | Linux オーケストレータ | 冪等キー必須。UI 手変更との衝突を差分で吸収 |
xcodebuild archive、IPA 出力、署名検証 | macOS 必須（専用 Mac クラウド推奨） | Linux 限界は Linux/Docker と iOS 境界 FAQ を参照 |
notarytool submit / staple、公証ポーリング | macOS 必須 | notarytool CI 記事 と併読 |
| レガシー Transporter 系 | macOS 必須 | 権限を絞ったロールアカウントで運用 |
3. 七ステップ：Issuer、キー、キュー、冪等
- Issuer 三角形の固定：Issuer ID、Key ID、
.p8パスを KMS に格納し、ジョブ開始時にマスク済みフィンガープリントをログへ。 - API クライアントを二系統化：Linux メタ自動化用と macOS ビルド用で App Store Connect ロールを分離。
- グローバルキュー導入：Redis/SQS 等で変異系呼び出しを直列化。初期値はアプリ×環境で飛行中 8〜12 リクエスト程度から。
- 書込の冪等化：ローカライズ PATCH は
git sha + localeなど安定キーで重複排除。 - 429 と 5xx の分岐：429 は指数バックオフ＋ジッター。5xx はリージョン／メンテを疑い、無闇にクライアント数を増やさない。
- Mac 受け入れ三点：
sw_vers、xcodebuild -version、キーチェーン解錠スモークを起動時に必ず。 - 劣化モード：エラー率が閾値を超えたら読取監視＋人手ゲートに落とし、メタ JSON スナップショットは 48 時間保持。
4. レビュー用の数値メモ
以下は出発点であり、Apple 公式の最新クォータと実測ヘッダで必ず校正すること。① 変異系 API の同時飛行はアプリ×環境で 8〜12 件前後を初期上限とし、ヘッダに余裕が見えたら段階的に緩める。② 429 後の初期待機はおおよそ 2〜4 秒、最大睡眠は約 120 秒を上限にジッターを載せる。③ IPA 受け渡し用の一時領域は IPA サイズの約 1.2〜1.8 倍を確保し、シンボル展開のピークを吸収。④ メタデータ JSON スナップショットは少なくとも約 48 時間保持し、UI 側の偶発変更と三方 diff できるようにする。⑤ 夜間の全件スキャンはページネーションカーソルを永続化し、ページ 1 からの再スキャンによる二次ストームを防ぐ。⑥ 5xx 比率が 5 分窓で悪化したら非必須スイープを一時停止し、キュー長と相関を見る。⑦ Linux オーケストレータと macOS ビルダの p95 を分離メトリクス化し、どちらを増やすべきかをインシデント時に即断できるようにする。
5. FAQ
Linux から直接アップロード REST を叩けるのでは？
成功して見えるケースはあっても、公式ツールチェーンと監査証跡を失いがち。本番は macOS 実行面を推奨する。
429 が多いときはキーを増やす？
まず並列度とキューを下げる。キー乱発は爆半径と説明責任の悪化を招く。
TestFlight 記事との役割分担は？
本稿はマシン境界とスロットリング。match と「ビルドのみ／アップロードのみ」ロールは TestFlight 記事 を読む。
6. macOS 実行面へ戻す理由
Linux でメタデータ自動化を広げるのはコスト効率が高いが、xcodebuild と公証まで HTTP だけで済ませようとすると、結局は非公式スクリプトの塊になり、障害時の切り分けが再起動頼みになる。ノート PC や雑多なデスクトップは電源・上行・観測性のばらつきが大きく、VPS 運用の作法とも噛み合わない。再現性・鍵管理・Xcode バージョン固定を一気通貫で満たすには、VPSMAC の M4 Mac クラウドのような SSH 前提の専用 macOS ノードをレンタルし、Linux オーケストレータとラベルで綺麗に分離するのが現実的だ。Apple ツールチェーンと AI エージェントを長時間同居させる用途でも、統一メモリと launchd 運用のしやすさが効いてくる。