2026 Mac クラウドで GitLab Runner（macOS）を運用：登録トークン、Executor、安全な並列数
Linux で Docker executor に慣れたチームほど、macOS では「アーキテクチャ不一致」「tags が合わず pending」「concurrent を上げすぎて DerivedData とキーチェーンが壊れる」でつまずきます。本稿は SSH 可能な Mac クラウドを GitLab のラベル付き容量として扱う前提で、Linux との差分、4 つの典型痛点、shell と custom の判断表、登録からスモーク job までの 5 ステップ、容量会議に貼れる硬指標、FAQ をまとめます。2026 年時点の Runner と GitLab の互換は必ず公式表で確認してください。
要点
1. 要約：Linux 習慣との差
Linux ではコンテナ境界で依存とファイルを隔離できます。macOS の xcodebuild は同一ユーザ空間で DerivedData・モジュールキャッシュ・キーチェーンを共有し、並列を CPU 数に合わせて上げるとリンクエラーやコンパイラ OOM がランダム赤として現れます。darwin-arm64 の GitLab Runner バイナリを誤って amd64 で動かすと、Rosetta 経由のツールチェーン混在で再現性が崩れます。目標は .gitlab-ci.yml の tags と Runner 登録 tags を一字一句揃え、concurrent とクリーンアップを config.toml に残し口頭運用をやめることです。Mac クラウドはオフィス Mac の睡眠や出張リスクを避け、VPS と同様に SSH とラベルで水平拡張できることが強みです。
2. 痛点：トークン、tags、キーチェーン、ディスク
- 登録スコープ：インスタンス用とプロジェクト用トークンを取り違えると Runner が別階層に現れ、ローテ後に
config.toml未更新だと online だが job を取らない状態になります。 - tags ドリフト：YAML が
macos-ios、Runner がmacos-arm64だけ、などミスマッチで永久 pending。再インストールのたびに README を更新しないと再発します。 - 署名と非対話セッション：shell executor はログインキーチェーンの前提が崩れるとコード署名が途中で消えます。CI 専用ユーザとパーティション設計が必要です。
- ディスク競合：並列 job が同じ DerivedData ルートを掃除し合うと中間成果物欠落で不安定化します。パス分離とタグ別プールが効きます。
3. shell と custom executor の判断表
| 観点 | shell | custom / 外部隔離 |
|---|---|---|
| 立ち上がり | 数時間単位でスモーク可能 | 数日〜数週の整備が現実的 |
| 隔離 | 弱い（同一ユーザ） | ワークスペースや VM で強化可能 |
| 署名 | ログイン文脈と揃うと簡単 | シークレット注入設計が要る |
| 並列戦略 | concurrent と tags で厳格化 | ホスト/ディレクトリ単位で分割しやすい |
| ディスク | パス規約＋定期クリーン | ジョブ後フックで消去やスナップショット |
| 向く規模 | 中規模以下の iOS 中心 CI | マルチテナントや強いコンプライアンス |
concurrent を保守的に保ち、DerivedData ルートを固定する方が総コストで勝ちやすいです。4. 登録から green job まで 5 ステップ
- インストール確認：
darwin-arm64のgitlab-runnerを配置し、uname -mと突合。Rosetta 下の amd64 ツールチェーン混在を禁止リストに入れる。 - register：正しいトークンで
gitlab-runner register。将来の YAML と同じ tags を入力し、config.tomlに[[runners]]が増えたか確認。 - executor と concurrent：
executor = "shell"、concurrentは 1〜2 から。PR 用 Runner 名とリリース用を分離。 - スモーク YAML：
sw_versとxcodebuild -versionのみの job で tags ルーティングと成果物を検証。 - クリーンアップと閾値：DerivedData/キャッシュパスを文書化。空き容量アラート。夜間バッチやパイプライン末尾で掃除。
5. メモリ・ディスク・並列の硬指標
中規模 Swift/iOS を想定した目安で実測必須。レビューでは p95 とキュー待ちを分離し、Runner 追加か concurrent 抑制かを判断。スワップ時はリンク尾が伸びやすいです。
- メモリ：単発 Archive で Apple Silicon 上 12〜18GB ピーク例。32GB マシンで三路同時フルビルドはスワップで p95 が悪化しがち。
- ディスク：キャッシュ有効時は空き 40GB 級のバッファを推奨。10GB 未満はリンク不安定が増えやすい。
- 並列開始値：custom 無しなら 1〜2 並列の
xcodebuildから。軽量 lint と重い Archive は tags で分離。 - ネットワーク：依存取得と Git が遠方だとフェッチ時間が線形に伸びる。PoC でフェッチ部分を切り出して記録。
- バージョン：GitLab メジャーアップは Runner をステージングで先に検証し、本番 tags を遅延スイッチ。
- ログ：
df -hと結果バンドルパスを毎ジョブで残し、ディスク競合疑いを即断。
6. Linux のみでは足りない理由と専用 Mac クラウドの価値
Linux Runner 群だけではネイティブ Xcode 署名と Apple 公式ツールチェーンを完走できません。ノート PC を借りる方式は可用性と監査で破綻しやすく、非 Apple ハードでの近似はライセンスと性能の壁があります。無人署名、Xcode 微バージョン固定、企業出口とレジストリ整合が必要なら、SSH と tags で増やせる専用 Mac クラウドを GitLab プールに載せるのが総保有コストで有利なことが多いです。Docker 風の隔離は macOS で価値がありますが運用面も増えるため、まずはネイティブ Mac クラウドで並列とディスクを制御する方が現実的なチームも多いです。開通を API 体験に近づけるには VPSMAC の 90 秒 API と CI/CD 連携記事で、発注から green までを一気通貫で設計してください。