iOSビルド用にMacでGitLab Runnerをセットアップする方法

最初に必要なもの

• 管理者権限があり、XcodeがインストールされたApple silicon Mac。
• Xcodeの初回起動が完了していること。不安ならsudo xcodebuild -runFirstLaunchを一度実行してください。
• GitLabのプロジェクトまたはグループでrunnerを管理する権限。
• 画面共有かモニター経由の、Macのデスクトップセッション。GitLabのmacOSインストールページでは、SSHセッションではなくローカルのGUIターミナルを使うよう指示しています。
• ジョブを実行するmacOSアカウント。そのユーザーでデスクトップにサインインしておきます。

1. runnerのバイナリをダウンロードする

GitLabは、Homebrewのformulaは自社で保守していないとして、公式バイナリを推奨しています。Apple siliconではarm64版を使います。新しいMacには/usr/local/binがまだないことがあるので、先に作成します。

sudo mkdir -p /usr/local/bin
sudo curl --output /usr/local/bin/gitlab-runner \
  "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"
sudo chmod +x /usr/local/bin/gitlab-runner
gitlab-runner --version

2. GitLabでrunnerを作成する

runner登録トークンは非推奨です。GitLabはGitLab 20.0で削除する予定です。現在の流れでは、まずUIでrunnerを作成し、runner認証トークンを受け取ります。このトークンはglrt-で始まります。

• プロジェクトで「設定」、「CI/CD」の順に開き、「Runner」を展開します。
• 「プロジェクトRunnerを作成」を選び、macOSを選択します。
• 「タグ」にmacos, xcodeと入力します。「タグのないジョブを実行」はオフのままにします。こうすると、Macを求めるジョブだけがここに来ます。
• 「Runnerを作成」を選び、トークンをコピーします。表示されるのは短い間だけです。

タグは現在、GitLab側のrunnerに保存されます。GitLabのドキュメントによると、--tag-listや--run-untaggedなどの設定は、UIかAPIでrunnerを作成するときにしか設定できません。あとでタグを変えるときは、runnerの編集ページで行います。

3. shell executorで登録する

GitLabのmacOSインストールページは、iOSとmacOSのビルドにshell executorを案内しています。ジョブはMac上で直接、あなたのユーザーとして、Xcodeとシミュレータを使って動きます。対話なしで登録するには次のようにします。

export RUNNER_TOKEN="glrt-paste-your-token-here"
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "shell" \
  --description "mac-mini-m6"

セルフマネージドのGitLabでは、代わりに自分のインスタンスのURLを使います。設定は~/.gitlab-runner/config.tomlに保存されます。GitLabによると、shell executorはメンテナンスモードです。それでもセキュリティ修正は提供されており、macOSのページがXcodeの作業に推奨しているのも今なおこれです。

4. サービスをインストールして起動する

cd ~
gitlab-runner install
gitlab-runner start
gitlab-runner status

これで~/Library/LaunchAgents/gitlab-runner.plistが作成されます。macOSではrunnerはユーザーのLaunchAgentで、GitLabはこれが唯一サポートされるモードだとしています。rootではなく、あなたとして動きます。iOSシミュレータとコード署名に必要なキーチェーンとログインセッションにアクセスできます。ログは~/Library/Logs/gitlab-runner.out.logとgitlab-runner.err.logに出力されます。

5. 再起動後も動くようにする

LaunchAgentは、そのユーザーがログインすると起動し、ログアウトすると止まります。つまり再起動後にrunnerが戻るのは、そのユーザーが自動でログインした場合だけです。GitLabのドキュメントも、この理由で自動ログインをオンにするよう書いています。「システム設定」の「ユーザとグループ」で設定します。次にMacがスリープしないようにし、実際に再起動して確かめます。

sudo pmset -a sleep 0
sudo shutdown -r now
# after it comes back, over SSH:
gitlab-runner status

ヘッドレスでの自動ログインには、気づきにくい失敗パターンがいくつかあります。macOS 27で新しく出たものもあります。詳しくはヘッドレスMacでの自動ログインにまとめました。

6. iOSアプリ用の.gitlab-ci.yml

ジョブがrunnerで動くのは、ジョブに書いたタグをrunnerがすべて持っている場合だけです。このジョブはmacosを要求し、テストを実行し、テストが失敗してもresult bundleを保存します。

stages:
  - test

ios_tests:
  stage: test
  tags:
    - macos
  script:
    - xcodebuild -version
    - rm -rf build/TestResults.xcresult
    - xcodebuild test -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.5' -resultBundlePath build/TestResults.xcresult
  artifacts:
    when: always
    paths:
      - build/TestResults.xcresult
    expire_in: 1 week

作業コピーを保持するマシンでは、rm -rfの行が重要です。xcodebuildは既存のresult bundleを上書きしないからです。Xcode 26.6で確認しました。

よくあるエラーと対処法

以下はGitLabのmacOSトラブルシューティングの項目からです。

• "launchctl" failed: Could not find domain for。installやstartをSSH経由で実行しています。Macのデスクトップでターミナルを開き、そこで実行してください。
• FATAL: Failed to start gitlab-runner: exit status 134。サービスが正しくインストールされていません。デスクトップからgitlab-runner uninstallを実行し、続けてinstall、startを実行します。
• Apple siliconでのkilled: 9。plistに書かれたログフォルダが存在し、あなたのユーザーが書き込める必要があります。
• Failed to authorize rights (0x1) with status: -60007。DevToolsSecurity -enableとsudo security authorizationdb remove system.privilege.taskport is-developerを実行します。
• git fetchが止まる。HomebrewのGitがキーチェーンの認証ヘルパーを追加していることがあります。runnerのユーザーでgit config --global --add credential.helper ''を実行します。
• ジョブが待ったまま動かない。ジョブのタグがrunnerのタグと一致していないか、タグのないジョブをrunnerが受け付けていません。

専用Macが役立つ理由

shell executorは、すべてのジョブで同じマシンを使い回します。XcodeのDerivedData、Swiftパッケージのチェックアウト、CocoaPodsのキャッシュが、パイプラインの間もディスクに残ります。時間がかかるのはまさにそこです。Xcode 26.6でWikipediaのiOSアプリを使った当社のベンチマークでは、小さな変更後の一般的なジョブの時間を測りました。ウォームなM6では27秒でした。同じジョブが、新規のGitHubホスト型macos-26 runnerでは269秒かかりました。クリーンビルドは86秒対183秒でした。

GitLabのホスト型Mac runnerで足りる場合

GitLabは自社でmacOS runnerを運用しています。2026年10月に読んだドキュメントでは、ベータ版とされています。PremiumとUltimateの顧客、オープンソースプログラム向けです。サイズは、4 vCPUで8 GBのM1と、6 vCPUで16 GBのM2 Proです。これらのプランを使っていて、パイプラインが1日に数回なら、ホスト型runnerで上の手順をすべて省けます。

信頼できないマージリクエストを実行するパブリックプロジェクトには、shell executorの専用Macを選ばないでください。GitLabは、shellのジョブが同じマシン上の他プロジェクトのコードを読めると警告しています。また、許可リスト用の固定IP、SLA、複数のリージョンが必要なら、MacRunは向きません。当社はどれも提供していません。

当社のハードウェアで試してみますか。MacRun側の設定はその他のCIシステムのページで、すべてのティアは料金ページで確認できます。