GitLab RunnerをmacOSでセルフホストするには?2026年ガイド
GitLab公式のmacOS手順では、Runnerのサービス方式としてユーザー単位のLaunchAgentを指定し、LaunchDaemonはサポート対象外としています。macOSでのインストール手順に従い、shell executorを使う場合は、信頼できるプロジェクトだけを受け入れることを条件に、実際にジョブを実行するMacへ導入してください。
この記事は、GitLab CI/CDでXcodeビルドやiOSテストを動かすためにmacOS Runnerを準備するエンジニア向けです。
WindowsやLinuxからMacノードを保守する担当者、遠隔のMacを継続的インテグレーションに使うか検討中のチームも対象です。
実行環境の適合性を先に確認する
GitLab Runnerは、ジョブを実行させるmacOSホストに導入します。GitLab本体をMacに設置する構成とは別の話であり、ビルドに必要なXcodeや依存ツールも実行ホスト側で用意します。
登録しただけでは、意図した環境でジョブが動くとは限りません。Runnerの登録状態、CI設定のタグ、executorの種類が一致しているかを、小さな検証ジョブで確かめます。登録時の項目や方法はGitLab Runnerの登録資料に沿って確認してください。
| 選択・確認項目 | macOS上の動作 | 判断の目安 |
|---|---|---|
| shell executor | ジョブをMacホスト上で実行します | Xcodeなどホストのツールを使う構成に適しますが、作業間の隔離は限定的です |
| Docker executor | macOS向けジョブでは、利用する実行環境やツールとの適合性を別途検証します | コンテナの名称だけで隔離やXcode利用を保証できると判断しないでください |
| Runnerタグ | CI設定に一致するRunnerへジョブを割り当てます | 専用タグを付け、意図しないRunnerへの流出をログで確認します |
| ジョブの検証 | Runner名、OS、実行ユーザー、ツール情報、成果物を確認します | 登録完了と、期待したビルド能力の確認を分けます |
GitLabはiOSやmacOS向けのジョブにshell executorを案内しています。shell executorの仕様を読み、コンテナ実行とは異なるホスト上の実行として設計してください。
ユーザーセッションと起動方式を評価する
macOS向けRunnerは、ログインユーザーに属するLaunchAgentとして動作させます。システム起動時にユーザーセッションなしで動くLaunchDaemonとは実行主体が異なり、GitLabの手順ではLaunchDaemonはサポートされません。AppleのLaunchAgentとシステムデーモンの説明も確認し、起動要件を取り違えないようにします。
ユーザーセッションへの依存は、キーチェーンの利用、GUIを必要とする処理、シミュレーター起動などに関係します。SSH接続ができることだけを根拠に、ログアウト後も同じ条件でジョブが動くとは判断できません。GitLabが記載する起動・再起動後の条件を確認し、必要であれば自動ログインを選ぶことになりますが、その場合はホストへ物理的にアクセスできる人や、ログイン中に参照可能な認証情報も含めてリスクを評価します。
Xcodeのツールチェーンをジョブログで確認する
macOS上にXcodeが存在していても、CIジョブが意図した開発者ディレクトリやコンポーネントを使うとは限りません。ジョブ内でツールの識別情報を記録し、インタラクティブな端末から実行した結果ではなく、Runnerの実行ユーザーから見た状態を証拠にします。
確認対象は、Xcodeの導入状態、アクティブな開発者ディレクトリ、初回起動時に必要なコンポーネントです。コマンドラインツールの要件はAppleのインストール資料を参照し、追加コンポーネントが必要な場合はAppleのXcodeコンポーネント案内を確認します。
検証では、ジョブログにXcodeの識別結果と開発者ディレクトリを出し、対象リポジトリの代表的なビルドを実行します。ビルドの成功と、シミュレーターの起動、署名、アーカイブなどの確認は分けてください。必要な能力を個別のジョブで検証すると、どの段階で失敗したのかを追いやすくなります。
shell executorの隔離範囲を決める
shell executorは、CIジョブをMacホスト上で実行します。これは作業ごとに独立したコンテナへ閉じ込める方式ではなく、GitLabも自托 Runnerのセキュリティ上の境界を別途検討するよう案内しています。Runnerのセキュリティ資料を基準に、ジョブを実行できるプロジェクトとアカウントを絞ってください。
導入前に、次の項目を確認します。
- Runnerが信頼できるプロジェクトのジョブだけを受け付ける設定になっています。
- 実行ユーザーにはビルドに必要な権限だけを付与し、管理者権限を常用しません。
- トークン、署名用の秘密情報、キーチェーンに、別のジョブからアクセスできない運用になっています。
- ジョブ終了後に残る作業ファイルやキャッシュを確認し、後続ジョブが不用意に利用できないようにします。
- 信頼度の異なるプロジェクトを同じホストで処理する場合は、分離要件を満たす別の実行構成を先に評価します。
Runnerの対象範囲や割り当ては、GitLabのRunnerスコープ管理資料に従って限定できます。タグを分けるだけで安全な隔離が得られるわけではありません。shell executorの権限境界を受け入れられないなら、タグ設定で補うのではなく、実行アーキテクチャを見直します。
FAQ:macOS Runnerの導入判断を整理する
GitLab RunnerはmacOSホストで実行できますか?
実行できます。Runnerとビルド依存ツールを、ジョブを処理するMacに準備します。GitLabサーバーをMacに移す必要はありません。登録後は専用タグを付けた最小ジョブで、実行先が想定したホストかを確認します。
macOSではどのexecutorを選びますか?
iOSやmacOSのビルドでは、GitLabが案内するshell executorが候補です。ただしジョブはホスト上で実行され、作業ごとの隔離は限定的です。信頼できるプロジェクトだけに割り当てられるかを、導入前に確認してください。
LaunchDaemonではなくLaunchAgentを使う理由は何ですか?
GitLabのmacOS向け手順がユーザー単位のLaunchAgentを指定し、LaunchDaemonをサポートしていないためです。ログイン状態やユーザーのキーチェーン、GUI・シミュレーターへの依存を確認し、自動ログインを使う場合は物理アクセスと認証情報のリスクも評価します。
遠隔のMacでXcodeジョブが動くことをどう検証しますか?
CIログから実行ユーザー、開発者ディレクトリ、Xcodeの識別結果を確認し、代表的なビルドを実行します。ビルド成功だけではシミュレーターや署名まで検証したことになりません。必要な作業ごとにジョブを追加し、成果物と失敗ログを保存してください。
ルーティングと検証証拠を揃える
最初のCIジョブは、Macの状態を識別できる短い処理にします。登録時に設定したタグをCI設定側でも指定し、ログから実際のRunnerと実行環境を確認します。Runnerのスコープやタグの管理を整理したうえで、専用タグ以外のジョブが誤って流れないかも検証してください。
次に、実際のプロジェクトを使った代表的なビルドを行い、次の証拠を残します。
- ジョブが割り当てられたRunnerと実行ユーザー
- macOS環境とXcodeの識別結果
- ビルドの成否、成果物、失敗時のログ
- シミュレーターや署名が必要な場合は、それぞれの検証結果
成果物を生成できたことと、リリースに必要な署名まで成功したことは別の判定です。検証項目をひとまとめにせず、チームが必要とする機能ごとに受け入れ条件を定めます。
再起動・ログアウト後の復旧性を確認する
個人の試用では動いても、メンテナンスや再起動後にRunnerが戻らなければ、継続的なCIノードには適しません。ログアウト時とホスト再起動後の挙動を実際の運用条件で確認し、Runnerのサービス状態、起動ユーザー、ログの所在を記録します。ログイン状態が必要な構成では、どの担当者がセッションを復旧させるのかも決めておきます。
更新時は、macOSやXcodeの変更後に代表的なビルドを再実行し、失敗時に前の環境へ戻す手順と担当者を定めます。復旧の検証が済んでいないノードを、重要なパイプラインの唯一の実行先にしないでください。評価結果に応じて、個人利用、管理されたチームジョブ、継続的な重要処理のどこまで任せるかを区別します。
導入前には、KuzCloudのコンソールで現在の接続方法を確認し、利用条件が判断できない場合はサポート案内で確認事項を整理してください。地域や契約期間も選定条件に含める場合は、日本向けプラン情報を参照し、掲載内容とCI要件が合うかを個別に照合します。
手元のWindowsやLinuxだけで済ませる構成では、macOS固有のXcode実行環境を用意できず、共有Macを使う場合はセッション維持や作業権限の管理が課題になります。自前のMacを常時運用する方法にも、調達と保守の負担があります。継続利用が未確定で、まず遠隔MacをCIノードとして評価したい場合は、必要なアクセス方法と利用期間を確認したうえで、KuzCloudのレンタルを候補に加えると、購入前に自チームのジョブ要件との適合性を判断できます。
macOSのビルド環境を、専用のMacで運用しませんか?
KuzCloudの専用Mac mini M4なら、演算資源を共有しない実機でmacOSのビルドやテストを実行できます。
管理者権限を備えた環境に、開発ツールや必要な実行環境を自由に導入できます。