Cara menyiapkan GitLab Runner di Mac untuk build iOS

Yang Anda butuhkan lebih dulu

• Mac Apple silicon dengan akses admin dan Xcode terpasang.
• Peluncuran pertama Xcode sudah selesai. Jalankan sudo xcodebuild -runFirstLaunch sekali jika Anda tidak yakin.
• Izin untuk mengelola runner di proyek atau grup GitLab Anda.
• Sesi desktop di Mac, lewat screen sharing atau monitor. Halaman instalasi macOS dari GitLab meminta Anda memakai terminal GUI lokal, bukan sesi SSH.
• Akun macOS yang akan menjalankan job. Login ke desktop sebagai pengguna itu.

1. Unduh binary runner

GitLab menyatakan tidak merawat formula Homebrew dan menyarankan binary resmi. Di Apple silicon, pakai build arm64. Mac yang masih baru mungkin belum punya /usr/local/bin, jadi buat dulu folder itu.

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. Buat runner di GitLab

Registration token untuk runner sudah usang. GitLab berencana menghapusnya di GitLab 20.0. Alur yang sekarang membuat runner di UI lebih dulu, lalu memberi Anda authentication token untuk runner. Token itu diawali glrt-.

• Di proyek Anda, buka Settings, lalu CI/CD, lalu buka bagian Runners.
• Pilih Create project runner dan pilih macOS.
• Di Tags, isi macos, xcode. Biarkan Run untagged jobs mati, agar hanya job yang meminta Mac yang masuk ke sini.
• Pilih Create runner dan salin token-nya. Token hanya ditampilkan sebentar.

Tag sekarang disimpan di runner di sisi GitLab. Menurut dokumentasi GitLab, pengaturan seperti --tag-list dan --run-untagged hanya bisa diatur saat runner dibuat, di UI atau lewat API. Ubah tag nanti dari halaman Edit milik runner.

3. Daftarkan dengan shell executor

Halaman instalasi macOS dari GitLab menyarankan shell executor untuk build iOS dan macOS. Job berjalan langsung di Mac, sebagai pengguna Anda, dengan Xcode dan simulator. Daftarkan tanpa prompt seperti ini:

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"

Di GitLab self-managed, pakai URL instance Anda. Pengaturannya tersimpan di ~/.gitlab-runner/config.toml. GitLab mencatat bahwa shell executor sedang dalam mode maintenance. Ia tetap mendapat perbaikan keamanan, dan tetap menjadi yang disarankan halaman macOS untuk pekerjaan Xcode.

4. Pasang dan jalankan layanannya

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

Perintah ini menulis ~/Library/LaunchAgents/gitlab-runner.plist. Di macOS, runner adalah LaunchAgent pengguna, dan menurut GitLab itu satu-satunya mode yang didukung. Runner berjalan sebagai Anda, bukan root. Ia bisa menjangkau keychain dan sesi login Anda, yang dibutuhkan iOS Simulator dan code signing. Log masuk ke ~/Library/Logs/gitlab-runner.out.log dan gitlab-runner.err.log.

5. Pastikan bertahan setelah reboot

LaunchAgent mulai saat penggunanya login dan berhenti saat logout. Jadi runner hanya kembali setelah reboot jika pengguna itu login sendiri. Karena itu dokumentasi GitLab meminta Anda menyalakan login otomatis. Lakukan di System Settings, bagian Users and Groups. Lalu cegah Mac agar tidak tidur, dan uji dengan reboot sungguhan.

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

Login otomatis di Mac headless punya beberapa cara gagal yang tidak terlihat, termasuk satu yang baru di macOS 27. Kami menuliskannya di login otomatis di Mac headless.

6. .gitlab-ci.yml untuk aplikasi iOS

Job hanya berjalan di runner yang punya semua tag yang diminta job itu. Job ini meminta macos, menjalankan test, dan menyimpan result bundle bahkan saat test gagal.

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

Baris rm -rf penting di mesin yang menyimpan working copy-nya. xcodebuild menolak menimpa result bundle yang sudah ada. Kami sudah mengeceknya di Xcode 26.6.

Error umum dan cara memperbaikinya

Daftar ini diambil dari bagian troubleshooting macOS di dokumentasi GitLab.

• "launchctl" failed: Could not find domain for. Anda menjalankan install atau start lewat SSH. Buka Terminal di desktop Mac dan jalankan di sana.
• FATAL: Failed to start gitlab-runner: exit status 134. Layanannya tidak terpasang dengan benar. Jalankan gitlab-runner uninstall, lalu install, lalu start, dari desktop.
• killed: 9 di Apple silicon. Folder log yang disebut di plist harus ada dan bisa ditulisi oleh pengguna Anda.
• Failed to authorize rights (0x1) with status: -60007. Jalankan DevToolsSecurity -enable dan sudo security authorizationdb remove system.privilege.taskport is-developer.
• git fetch hang. Git dari Homebrew bisa menambahkan credential helper keychain. Jalankan git config --global --add credential.helper '' sebagai pengguna runner.
• Job tertahan dan tidak jalan. Tag-nya tidak cocok dengan tag runner, atau job tidak punya tag dan runner tidak menerima job tanpa tag.

Mengapa Mac khusus membantu

Shell executor memakai mesin yang sama untuk setiap job. DerivedData Xcode, checkout Swift package, dan cache CocoaPods tetap di disk di antara pipeline. Di situlah waktu dihemat. Dalam benchmark kami dengan aplikasi iOS Wikipedia di Xcode 26.6, kami mengukur job biasa setelah perubahan kecil. Hasilnya 27 detik di M6 yang hangat. Job yang sama butuh 269 detik di runner macos-26 baru yang di-hosting GitHub. Clean build butuh 86 detik, dibanding 183 detik.

Kapan runner Mac hosted dari GitLab sudah cukup

GitLab menjalankan runner macOS miliknya sendiri. Dokumentasinya, yang kami baca pada Oktober 2026, mencantumkannya sebagai beta. Runner itu untuk pelanggan Premium dan Ultimate serta program open source. Ukurannya M1 dengan 4 vCPU dan 8 GB, serta M2 Pro dengan 6 vCPU dan 16 GB. Jika Anda memakai salah satu paket itu dan menjalankan beberapa pipeline sehari, runner hosted menghemat semua langkah di atas.

Jangan pilih Mac khusus dengan shell executor untuk proyek publik yang menjalankan merge request tidak tepercaya. GitLab memperingatkan bahwa job shell bisa membaca kode proyek lain di mesin yang sama. Lewati juga MacRun jika Anda butuh IP statis untuk allowlist, SLA, atau lebih dari satu region. Kami tidak menyediakan satu pun dari itu.

Siap mencobanya di hardware kami? Halaman sistem CI lain kami membahas sisi MacRun, dan halaman harga mendaftar setiap tier.