Macはネットワークに戻ったのに、GitLab Runnerだけがオフラインのままです。
最短の修復方針は、再インストールではありません。GitLab RunnerはmacOSでユーザー単位のLaunchAgentとして動くため、専用CIアカウント、FileVaultの解除、ユーザーセッション、Keychainを順に確認し、LaunchDaemonへ勝手に変更しないことが出発点です。GitLab公式のmacOS向けサービス設定も、この前提で確認します。
このガイドは、再起動後に異地のMacを復旧させたい企業IT責任者向けです。
Runner自体、ジョブのルーティング、macOSのログイン状態のどこで止まったかを切り分けたい開発生産性責任者にも適しています。
自動復旧とFileVault、署名情報の分離を監査可能な境界として設計したいセキュリティ・リリース担当者にも役立ちます。
最初に分けるべき状態
「ホストが起動した」と「Runnerがジョブを受けられる」は同じ状態ではありません。電源投入、ディスクのロック解除、ユーザーのログイン、LaunchAgentの読み込みは、それぞれ別に確認します。
最初にGitLab画面だけを見て再登録しないでください。現在のログインユーザー、Runnerのサービス状態、設定ファイルの所有者を記録してから、故障範囲を絞ります。
| 確認対象 | 起きている状態 | 次に確認すること |
|---|---|---|
| Mac本体 | 電源とネットワークは復旧 | Remote Loginまたは管理経路 |
| FileVault | 起動前のディスク解除待ち | 解除方法と監査記録 |
| ユーザーセッション | CI用アカウントが未ログイン | 対象アカウントでのログイン |
| GitLab Runner | オフライン表示 | LaunchAgentとログ |
| ジョブ実行 | Runnerはオンライン | Keychain、Xcode、シミュレーター |
macOS GitLab Runnerがログインユーザーを必要とする理由は、公式のサービス方式がユーザーセッションに結び付いたLaunchAgentだからです。Appleのlaunchdジョブ設計でも、AgentとDaemonは異なる実行境界として説明されています。
LaunchAgentとLaunchDaemonの境界
なぜ再起動後に自動起動しないのか
主な原因は、Runnerをインストールしたアカウントと、再起動後にログインするアカウントが異なることです。設定ファイルやLaunchAgentが別ユーザーのホームディレクトリに残っている場合、サービスを再登録しても対象のセッションでは読み込まれません。
確認対象は次の順番です。
- [ ] GitLab Runnerをインストールしたユーザー名を記録する
- [ ] 再起動後にログインしたユーザー名と一致させる
- [ ] 設定ファイルがCI専用アカウントのホームディレクトリにあるか確認する
- [ ] LaunchAgentの読み込み結果とプロセス所有者を確認する
- [ ] GitLab側のRunner IDと登録先プロジェクトを照合する
- [ ] 同じMacに残る古い設定ファイルを一覧化する
LaunchDaemonへ変更できるか
技術的に別のサービス構成を作ることと、GitLab公式のmacOS Runner運用として支持されることは別です。ユーザーセッション、ログインKeychain、GUIを必要とするXcodeやシミュレーターを扱う場合、LaunchDaemon化は実行コンテキストを変えてしまいます。
したがって、開機時の常駐だけを理由にLaunchDaemonへ変更するのは避けます。AppleのAgentとDaemonの違いを確認し、公式のユーザー単位サービスを維持したまま、ログイン方式と復旧手順を設計します。
注意：Runnerがオンラインになっても、本番ビルドが成功するとは限りません。オンライン表示は、ジョブを受け取る前段階の確認にすぎません。
FileVaultと無人復旧のトレードオフ
FileVaultを有効にしたMacでは、自動ログインを当然の前提にできません。Appleは自動ログインの制約を説明しており、FileVaultとの組み合わせによって、起動後に認証操作が必要になる構成があります。
企業では「暗号化されたまま無人で復旧する」ことと「電源投入後にCIセッションまで自動で進む」ことを同じ要件にしないことが重要です。AppleのFileVault管理資料に照らし、対象Macのチップ、macOS、管理ポリシー、ネットワーク到達性を個別に確認します。
| 運用方針 | 利点 | 失うもの・確認事項 |
|---|---|---|
| 自動復旧を優先 | 現地操作への依存を減らせる | 認証情報の保管、監査、端末管理が必要 |
| FileVault保護を優先 | 保存データの保護境界を維持できる | 起動後の解除操作が復旧経路に残る |
| 専用待機Macを用意 | 1台の復旧待ちでリリースを止めにくい | 構成同期、署名情報、追加費用の管理が必要 |
Remote Loginを利用する場合も、まずMacがログイン前後のどの状態にあるかを確認します。AppleのRemote Login設定は接続経路の説明であり、FileVault解除やユーザーセッションの代替ではありません。
復旧用アカウントは、共有パスワードではなく、担当者、利用目的、承認記録、使用後の変更手順まで残します。自動化を強めるほど、認証情報を誰が扱えるかを狭く定義する必要があります。
オンライン表示と実行能力の差
RunnerがGitLab上でオンラインでも、Keychainやシミュレーターへアクセスできない場合があります。ログインKeychain、システムKeychain、CIサービスアカウント、配布用署名IDを一つの「証明書設定」として扱わないでください。
最小テストは、負荷の小さい順に分けます。
- [ ] 一般的なシェルスクリプトが実行できる
- [ ] CIアカウントからXcodeのビルド処理を開始できる
- [ ] 必要なシミュレーターを起動できる
- [ ] 署名用Keychainを意図した条件で参照できる
- [ ] テスト用成果物を保存できる
- [ ] 実際のリリースに近いジョブを隔離環境で完了できる
この分割により、Runnerの再接続失敗と署名環境の失敗を混同せずに済みます。ログを詳細化する場合は、GitLabのトラブルシューティング資料に従い、変数や資格情報がログへ出ない時間帯と保管先を決めます。
残留サービスとジョブルーティング
誤ったアカウントで再インストールすると、複数の設定ファイル、LaunchAgent、system IDが同じMacに残ります。見た目は一つのRunner障害でも、実際には古いプロセスが別の登録情報で待機していることがあります。
次の比較で整理します。
| 症状 | 可能性 | 判断材料 |
|---|---|---|
| GitLabで完全にオフライン | サービス未読込、未ログイン、通信不通 | プロセス所有者とサービス状態 |
| オンラインだがジョブを取らない | タグ、保護ブランチ、対象範囲の不一致 | Runnerの登録条件 |
| ジョブ開始後に失敗 | Keychain、Xcode、シミュレーター | 最小ビルドの結果 |
| 複数Runnerが表示される | 残留設定、重複登録 | ID、設定ファイル、ログ |
| 一部プロジェクトだけ失敗 | ルーティング条件 | タグとプロジェクト・グループ範囲 |
Runnerのタグや保護ブランチ、プロジェクト・グループ範囲は、GitLabのRunner設定資料で照合します。タグ不一致を「再起動後のオフライン」と誤認すると、不要な再登録や権限変更が発生します。
再起動後の本番受入れ
オンライン表示だけで本番投入しません。再起動の計画、FileVault解除、ユーザーセッション、LaunchAgent、Runnerの接続、最小ビルド、実ジョブの順に証拠を残します。
| 受入れ段階 | 記録する証拠 | 失敗時の処置 |
|---|---|---|
| 再起動 | 実施者と承認記録 | 変更を止めて状態保存 |
| ディスク解除 | 解除方法と担当者 | 復旧アカウント経路を確認 |
| ユーザーログイン | CIアカウントのセッション | 対象アカウントを再確認 |
| Runner接続 | GitLab画面とサービスログ | LaunchAgentを確認 |
| 最小ビルド | ジョブログと成果物 | Keychain・Xcodeを分離調査 |
| 実リリース相当 | 署名、テスト、成果物 | 本番投入を保留 |
異常終了や電源断でも同じ確認を行います。アカウントの権限を外した場合に、Runnerが停止すること、署名情報へアクセスできなくなること、残留サービスが残らないことも検証対象です。
既存のMacを継続利用する場合は、Macの調達条件とCI要件を照合し、物理端末の所有、交換、現地対応を誰が担うかを明文化します。遠隔運用を前提にするなら、単一ノードが現地ログインだけに依存していないかを、MESHLAUNCHのMac環境と比較して評価できます。
今週の復旧判断
今週は、まず専用CIアカウントの所有関係、LaunchAgentの読み込み、FileVault解除経路、Keychainの最小テストを一つの記録にまとめます。その後、計画再起動と異常電断を別々に実施し、Runnerのオンライン表示ではなく実際のXcodeジョブ完了まで確認します。
現在のMacを使い続ける方法は、物理インターフェース、長期の固定負荷、社内管理ポリシーを満たしやすい一方、現地ログイン、故障交換、単一ノード停止、署名環境の復旧を社内で抱えます。単一台の復旧が担当者の手操作に残るなら、隔離した遠隔Macを予備のビルドノードとしてレンタルし、受入れ条件と交換手順を先に検証する方が、リリース停止時の判断を明確にできます。
必要なのは、Macを増やすことではなく、再起動後に誰が、どの認証境界で、どのジョブを完了させたかを証明できる構成です。恒常的な高負荷や物理ポートが必要な場合は自社保有を優先し、短期の検証、待機系、チームの一時的なCI容量にはMESHLAUNCHの遠隔Macを候補に加えるのが現実的です。