GitLab CI Mac Runnerはどう構築する？2026年デプロイ受け入れガイド

SECTION 011. ノードの適性を判定する：GitLab CI Mac Runnerは専用利用が前提です

GitLabのmacOS Runnerは、ユーザーのLaunchAgentとして動作し、ログイン中のユーザーセッションに依存します。GitLabのmacOS向け導入資料にあるこの条件から、まず専用の信頼できるMacで試行し、共有ノードや未信頼コードを受け付けるノードにはそのまま導入しないでください。

症状：Runnerがオンラインでも、ジョブ実行やXcodeビルド、再起動後の復旧まで確認できたとは限りません。
最短の対処：Appleプラットフォームのジョブに用途を絞り、実ジョブとログイン状態の復旧を確認してから利用範囲を決めます。

iOS／macOS開発者：AppleプラットフォームのビルドやテストをGitLab CIのMacノードで実行したい方。
DevOps担当者：Runnerの登録、保守、ログアウトや再起動後の動作を確かめたい方。
開発基盤・セキュリティ担当者：Shell executorの隔離範囲を踏まえてノードの利用条件を決めたい方。

GitLab RunnerはmacOSに導入できます。ただし、すべてのジョブをMacへ移す必要はありません。XcodeやmacOS固有のツールが必要なジョブをMacに割り当て、OSに依存しない処理は既存のCI環境に残すと、権限と保守対象を分けやすくなります。

GitLabが説明するShell executorは隔離能力に制約があり、メンテナンスモードに位置付けられています。executorの状態とShell executorの仕様を確認し、コンテナと同等の隔離があるものとして扱わないでください。

SECTION 022. 導入前に実行アカウントとXcodeを記録する

Runner用のアカウント、対象プロジェクト、許可するコードの範囲、問題発生時の回退先を先に決めます。普段使いのMacを共有すると、作業ファイルや認証情報がCIジョブから参照される可能性があり、あとから安全な境界を説明しにくくなります。

プロジェクトがXcode本体を必要とする場合、Command Line Toolsだけで要件を満たすと決めつけないでください。AppleのXcode Command Line Toolsリファレンスとインストール手順で必要なツールを確認し、対象ノードで実際のXcodeとSDKを検証します。未確認のバージョン互換性や性能を前提にせず、使用するDeveloperディレクトリと結果を記録してください。

SECTION 033. ログイン中のセッションでRunnerを登録する

GitLabのmacOS向け手順に従ってRunnerを用意し、プロジェクトまたはグループで管理する登録情報を使います。登録時には対象URLや認証トークンを公開ログや共有文書に貼らず、GitLabのRunner登録手順で現在の方法を確認してください。

Homebrewを使う構成なら、公式の導入手順とノードの管理方針を照らし合わせて実行します。

brew install gitlab-runner
gitlab-runner register

登録時はGitLabのURL、発行済みトークン、Runnerの説明、ジョブタグ、executorを指定します。Xcode CIのようにmacOS上のツールを直接使うジョブではShell executorが候補になりますが、未信頼コードを扱わないことを先に確定してください。

macOSのLaunchAgentはユーザーのログインセッションに結び付いており、システム起動時に動くLaunchDaemonと同一ではありません。ログイン状態を維持するためだけに自動ログインを有効にするのは避け、端末の物理的な管理、認証情報へのアクセス、運用上の必要性を比較して決めます。ここでの合格条件は、登録できたことだけでなく、意図したアカウントでRunnerが起動していることです。

SECTION 044. 最小のCIジョブでXcodeの実行環境を検証する

Runnerのオンライン表示、ジョブのスケジュール、Shell executorによるコマンド実行、Xcodeを使ったビルド成功は別々の確認項目です。次のように、最初はタグを限定した単純なジョブを動かし、ログに環境の証拠を残します。

stages:
  - verify

mac_environment:
  stage: verify
  tags:
    - "<MAC_RUNNER_TAG>"
  script:
    - whoami
    - pwd
    - xcode-select -p
    - xcodebuild -version
    - xcodebuild -list -project "<PROJECT_PATH>"
    - xcodebuild -project "<PROJECT_PATH>" -scheme "<SCHEME>" build

<MAC_RUNNER_TAG>、<PROJECT_PATH>、<SCHEME>は実際の設定に置き換えます。ジョブログで実行ユーザーと作業ディレクトリを確認し、xcode-select -pの結果が選定したDeveloperディレクトリと一致するか、xcodebuild -versionが想定したXcodeを示すかを見ます。

ビルドコマンドが終了しただけで受け入れず、指定したプロジェクトとSchemeが実際に解決され、対象のビルドが成功したことまでログで確認してください。失敗した場合は、Runnerタグの不一致、リポジトリのチェックアウト、Xcode選択、Scheme名を順番に切り分けます。これにより「Runnerがオンライン」と「Xcode CIが通る」を混同せずに済みます。

SECTION 055. 対象を広げる前に資格情報と隔離境界を確認する

最初のジョブが成功しても、署名や複数プロジェクトの実行をすぐに許可しないでください。ジョブが参照できるリポジトリ、作業ディレクトリに残るファイル、Keychain、署名証明書とプロビジョニング資産を個別に棚卸しします。GitLabの自ホストRunner向けセキュリティ資料を基準に、ジョブの実行主体がアクセスできる情報を確認してください。

次のいずれかに当てはまる場合は、共有利用や高権限の署名ジョブへの拡大を止めます。

• 未信頼コードが実行される、またはプロジェクト間でジョブ実行者を分けられない。
• 前のジョブのファイルや認証情報が、次のジョブから参照される可能性を排除できない。
• 署名資産の利用者、保管場所、失効・削除手順が明確でない。

隔離を強める必要があるなら、Shell executorを隔離コンテナのように扱うのではなく、GitLabがサポートする別の実行トポロジーを評価します。チームでMac CIの導入範囲を検討する際は、MACNOXのMac環境案内も候補の確認に使えますが、環境の適合性は実プロジェクトのジョブで判断してください。

SECTION 066. ログアウトと再起動を試し、運用可否を判定する

通常のビルドが通ったら、Runnerのプロセス状態だけでなく、ユーザーのログアウト、システム再起動、Runnerサービスの停止・復帰を実際の運用条件で検証します。macOS Runnerはユーザーセッションへの依存があるため、ログアウト後や再起動後にジョブが受け付けられるかを記録し、オンライン表示だけを復旧の根拠にしないでください。

• [ ] Runnerが意図したタグのジョブを受け取ることを確認した。
• [ ] チェックアウト後の実行ユーザーと作業ディレクトリを確認した。
• [ ] xcode-select -pとxcodebuild -versionで実際のツールチェーンを記録した。
• [ ] 対象プロジェクトとSchemeを使うビルドが完了した。
• [ ] Keychain、署名資産、作業ファイルの参照範囲を確認した。
• [ ] ログアウト、再起動、Runnerの再起動後にジョブが再び実行できるか確認した。
• [ ] 復旧できない場合の停止・回退先を決めた。

ジョブの記録、資格情報の境界、再起動後の挙動がそろって初めて、試行継続・限定的な本番投入・構成変更のいずれかを判断できます。ログインセッションの維持や必要な隔離を運用で保証できないなら、共有利用は保留してください。

SECTION 07よくある疑問

GitLab RunnerはmacOSにも導入できますか？

導入できます。GitLabはmacOS向けのRunner手順を公開しており、Appleプラットフォームの処理をMac上で実行できます。ただし、導入可能であることは共有利用の安全性を意味しません。信頼できるコードに限定した専用ノードで、ユーザーセッションとジョブの実行を確認してください。

GitLab CIのMacジョブでは、どのexecutorを選びますか？

XcodeなどmacOS上のツールを直接利用するジョブではShell executorが候補です。一方、これは隔離コンテナではなく、GitLabの資料ではメンテナンスモードとして案内されています。未信頼コードを実行する共有ノードには使わず、より強い隔離が必要な場合は別の対応トポロジーを評価します。

Macのログアウト後や再起動後もRunnerは動きますか？

macOSのRunnerはユーザーのLaunchAgentとして動作し、ログイン済みセッションに依存します。そのため、ログアウトや再起動後のジョブ受付は、オンライン表示だけでは判断できません。自動ログインを安易に有効にせず、チームの安全要件に沿った状態で復旧試験を行ってください。

想定したXcodeが使われているか確認する方法はありますか？

ジョブログにxcode-select -pとxcodebuild -versionを出し、選択中のDeveloperディレクトリとバージョンを確認します。さらに対象プロジェクトでxcodebuild -listを実行し、指定Schemeのビルドまで通してください。Runnerのオンライン表示やCommand Line Toolsの存在だけでは、必要なXcodeでビルドできた証明になりません。

SECTION 08次の一手は、試行条件を満たすMac環境の確保から

共有Macは個人作業との境界が曖昧になりやすく、LinuxノードではXcodeを必要とするジョブを実行できず、自前のMacでは専用ノードの維持や復旧も運用側の負担になります。まずセキュリティ条件とジョブの適合性を通し、短期間の検証環境が必要なら、MACNOXの料金案内で利用条件を確認してから実プロジェクトを試してください。継続的な高負荷運用や物理接続が必要な用途は、レンタルが適切とは限りません。

SECTION 09よくある質問 FAQ