GitLab公式のmacOSインストール手順では、Runnerはユーザー単位のLaunchAgentとして動作し、実行にはログイン中のユーザーセッションが必要です。macOSへのインストール説明
再起動後にオフラインなら、まず実行アカウントのログイン状態、LaunchAgentの起動、GitLabへの接続を確認してください。無人復旧のための自動ログインは、アクセス権と端末の管理方法を確認してから判断します。
この記事は、旅先からiOSビルドを保守するデジタルノマドや遠隔開発者、独立開発者向けです。
小規模チームで自管Runnerの保守負担や予備のビルド経路を検討している場合にも役立ちます。
症状から障害の場所を絞る
「ジョブが動かない」という表示だけでは、Mac上のRunnerが停止しているとは限りません。GitLabでRunnerがオフラインなのか、ジョブのタグが一致しないのか、プロジェクトにRunnerが割り当てられていないのかを先に分けます。
GitLabではRunnerの状態を画面やAPIで確認できます。APIのstatusフィールドを含む状態情報は、Runner APIの説明で確認できます。ジョブに付けたタグとRunnerのタグが一致しないとジョブを受け取れないため、Runnerのタグ照合ルールも確認してください。
| 見えている状態 | まず調べる場所 | 次の判断 |
|---|---|---|
| GitLab上でRunnerがオフライン | Macのログインセッション、LaunchAgent、Runnerプロセス | 起動していなければMac側の復旧へ |
| Runnerはオンラインだがジョブが保留 | ジョブのタグ、Runnerの登録範囲、プロジェクトとの関連付け | 条件が合わなければGitLab側の設定を修正 |
| ジョブは開始するが失敗 | ジョブログ、実行ユーザーの権限、開発環境 | Runnerのオンライン状態とは別に原因を調査 |
| ジョブは成功扱いだがアプリを作れない | Xcodeの選択状態、必要なコンポーネント、ビルドログ | Xcode側の環境を確認 |
Macを再起動した後、GitLab Runnerがオンラインにならない原因は何ですか。
まず、Runnerを動かすユーザーがmacOSにログインしているか確認します。GitLabのmacOS向けRunnerはLaunchAgentとして動くため、システム起動だけでなくユーザーセッションの状態が関係します。GitLabのmacOSインストール手順
注意：SSH接続が切れたことだけで、Runnerも停止したとは判断できません。再起動、ユーザーのログアウト、SSHの切断は別の状態です。実際のサービス状態とGitLab上の表示をそれぞれ確認してください。
Runnerがオフラインなら、Mac側の起動状態を確認する
GitLabの画面でオフラインと分かったら、Macに接続し、Runnerを実行しているアカウントで操作します。管理者アカウントとは別のユーザーでRunnerを登録している場合、別アカウントのセッションを確認しても原因を見誤ることがあります。
GitLab macOS Runnerが起動しているか、どう確認できますか。
Runnerの実行ユーザーでgitlab-runner statusを試し、続けてgitlab-runner verifyで登録先への接続を確認します。コマンドの用途やオプションはGitLab Runnerコマンドのリファレンスを参照してください。コマンドが見つからない、またはサービスの状態が取れない場合は、実行ユーザーとインストール方法を見直します。
次に、ユーザーのLaunchAgentが読み込まれているかを確認します。macOSのアクティブなユーザーセッションでlaunchctl listを実行し、Runnerに関係する項目があるかを調べてください。表示がない場合は、GitLabのインストール手順に沿ってLaunchAgentの配置と起動を確認します。出力だけで判断できない場合は、Runnerのログも照合します。
LaunchAgentとLaunchDaemonは同じものではありません。LaunchAgentはユーザーのログインセッションに結び付くため、ログアウト後もシステムサービスのように動き続けると決めつけないでください。LaunchDaemonへ置き換えれば同じ設定で復旧する、と考えるのも避けます。GitLab公式のmacOS手順が示す実行形態を基準に、現在のインストール状態と照らし合わせてください。
ユーザーのログアウト後も動くと推定しない
遠隔Macからログアウトすると、GitLab Runnerは動き続けますか。
LaunchAgentとしてユーザーセッションで動作している構成では、ログアウト後もRunnerが稼働するとは仮定できません。ログアウトの前後でgitlab-runner status、GitLab上の状態、ジョブの受け付けを確認し、使っている構成で実際にどうなるかを記録します。
たとえば、旅先でSSHからMacを再起動し、ログイン画面のままにしていると、Runnerを起動するユーザーセッションが存在せず、GitLabの画面ではオフラインに見えることがあります。一方、単にSSHを閉じた場合は、ユーザーセッションが残っている可能性があります。接続の切断をログアウトと同一視せず、Mac側の状態で切り分けてください。
| 運用方法 | 再起動後に見る項目 | 主な利点 | 主な注意点 |
|---|---|---|---|
| ユーザーがログインしてからRunnerを起動 | セッション、LaunchAgent、GitLabへの接続 | 自動ログインを避けやすい | ログイン操作が必要 |
| 自動ログインを設定 | 起動後のセッション、Runner状態、アクセス制御 | ユーザーセッションが必要な処理を再開できる場合がある | 端末への物理アクセスとアカウント保護の境界が変わる |
| 別のビルド経路を用意 | 代替環境でのジョブ実行と成果物 | 1台のMacの復旧待ちを避けやすい | 設定と保守対象が増える |
自動ログインを設定する前に、許容できるリスクを決める
GitLabのmacOSインストール説明では、自動ログインをRunnerの起動に関連する選択肢として扱っています。ただし、それはすべての環境で推奨される設定という意味ではありません。自動ログインの条件や管理上の注意点は、Appleの自動ログイン説明と照らし合わせて判断してください。
自動ログインを有効にすると、再起動後にユーザーセッションを開始できる場合があります。その一方で、Macに物理的にアクセスできる人が利用できる範囲や、ユーザーアカウントとプロジェクトの認証情報をどう守るかを再評価する必要があります。アクセス制御や保管する資格情報を確認できないなら、自動ログインを有効にする前に、手動ログインや別のビルド経路を検討してください。
メリットは、再起動後のユーザーセッションを自動で用意できる可能性があることです。デメリットは、端末の物理的な保護やアカウント管理が弱い場合に、利用範囲が広がり得ることです。セキュリティ上の許容範囲を決めず、「Runnerがオンラインになるから」という理由だけで設定しないでください。
Runnerがオンラインでも、ジョブとXcodeを個別に検証する
Runnerがオンラインであることは、ジョブを受け取れることや、Xcodeビルドが成功することを保証しません。GitLabの登録範囲とタグがジョブの条件に合っているかを見てから、実際のジョブログで実行ユーザー、作業ディレクトリ、失敗したコマンドを追います。
自動ログイン後にRunnerがオンラインなら、ジョブも自動で実行できますか。
オンライン表示だけでは判断できません。Runnerのタグとジョブのタグ、プロジェクトへの割り当て、Runnerの受け入れ条件が一致している必要があります。GitLabのタグ設定説明に沿って照合し、ジョブが開始した後はログを確認してください。
ジョブが始まってから失敗する場合は、Xcodeの開発ディレクトリと必要なコンポーネントを確認します。xcode-select -pで選択中の開発ディレクトリを調べ、ジョブログに記録されたツールやSDKのエラーと照合してください。コマンドラインツールの導入条件はAppleのXcodeコマンドラインツール説明、追加コンポーネントはAppleのXcodeコンポーネント説明で確認できます。
再起動演習で自管を続けるか決める
設定を変えたら、実運用に戻す前に再起動からビルドまでを一続きで確認します。以下の順序で、どこで止まったかを記録してください。
- Runnerの実行アカウントを特定し、そのアカウントのログイン状態を確認します。
- Macを再起動し、設定した方法でユーザーセッションが始まるか確認します。
- LaunchAgentとRunnerの状態を調べ、GitLab上でもオンライン表示になるか照合します。
- 対象プロジェクトからジョブを実行し、タグと登録範囲が一致していることを確認します。
- ジョブの実行結果とXcodeビルド結果を確認し、失敗した段階を記録します。
判定は、サービス起動、GitLabのスケジューリング、ジョブ実行、Xcodeビルド成功の各段階で分けます。サービスが起動してもジョブが来ないならGitLab側の条件を調べます。ジョブは動くがビルドに失敗するなら、実行ユーザーやXcode環境を調べます。ユーザーセッションが必須で、自動ログインのリスクを受け入れられず、手動復旧も難しい場合は、代替のビルド経路を用意する方が運用に合うことがあります。
演習では「再起動後にオンラインになった」だけを合格にしないでください。実際のプロジェクトのジョブがRunnerに割り当てられ、Xcodeビルドまで完了した記録を残します。
旅先で保守する環境を選ぶ
手元のMacを遠隔操作する構成は、物理端末を管理できる一方、電源や接続、再起動後のログイン、Xcode環境の保守を自分で担います。出先から復旧できない時間が納期に直結するなら、別のビルド経路を並行して用意するか、継続してアクセスできるリモートMac環境を検討してください。利用場所や接続方法を先に確認する場合は、MACCOMEのMac利用案内とリモートMacの案内を参照できます。
遠隔の自管Macには、ログイン操作や物理アクセスの管理、RunnerとXcodeの更新という負担があります。必要な期間だけmacOSのビルド環境を使いたい場合は、MACCOMEのリモートMac環境を候補にできます。ただし、長期にわたり安定した負荷で使う場合や、手元での物理インターフェース操作が必須の場合は、自前のMacの方が適することもあります。まずは上記の再起動演習で、必要なセッション条件と復旧手順を確かめてから選んでください。