Cara menjalankan agen Buildkite di Mac

Yang Anda butuhkan lebih dulu

• Cluster Buildkite, dan izin untuk mengelola token agen dan queue-nya. Anda harus menjadi org admin atau cluster maintainer.
• Mac dengan macOS 11 atau lebih baru. Itu batas minimum yang disebutkan Buildkite. Apple silicon, Homebrew, Xcode, dan akses admin.
• SSH key yang bisa dipakai agen untuk meng-clone repository Anda.

1. Buat queue dan token agen

Di Buildkite, pilih Agents untuk membuka halaman Clusters, lalu pilih cluster Anda. Di halaman Queues, pilih New Queue. Beri key macos dan pilih Self hosted. Lalu buka Agent Tokens, pilih New Token, tambahkan deskripsi, dan buat token-nya. Salin nilainya. Buildkite hanya menampilkannya sekali.

Formulir token punya field Allowed IP Addresses. Biarkan kosong di MacRun. Mac kami tidak punya IP publik statis, jadi aturan CIDR akan mengunci agen di luar.

2. Pasang agen dengan Homebrew

brew tap buildkite/buildkite
brew trust buildkite/buildkite
brew install buildkite/buildkite/buildkite-agent

Homebrew 7.0.7, versi di Mac kami pada Oktober 2026, menolak formula dari tap pihak ketiga sampai Anda memercayainya. Itulah baris tengahnya. Formula-nya sekarang bernama buildkite-agent@3, dan nama lama di dokumentasi Buildkite masih mengarah ke sana.

Di Apple silicon, file-nya masuk ke bawah /opt/homebrew:

• Config: /opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
• Hooks: /opt/homebrew/etc/buildkite-agent/hooks
• Log: /opt/homebrew/var/log/buildkite-agent.log

Jalankan brew info buildkite-agent untuk melihat path persisnya di mesin Anda.

3. Tambahkan token dan tag queue

Dokumentasi Buildkite memakai sed untuk mengganti token placeholder. Ganti teks berhuruf kapital dengan token Anda.

sed -i '' "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg
cat "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg | grep token

Lalu buka file yang sama dan atur baris tags, agar agen bergabung ke queue Anda:

tags="queue=macos"

Satu agen hanya masuk ke satu queue self-hosted di sebuah cluster. Tanpa tag queue, agen masuk ke queue default. Jika cluster tidak punya queue self-hosted default, menurut Buildkite agen gagal tersambung.

4. Uji, lalu jalankan sebagai layanan

Jalankan sekali di foreground. Agen seharusnya muncul di daftar agen milik cluster.

buildkite-agent start

Hentikan dengan Control C. Formula Homebrew menyertakan definisi layanan. Layanan itu menjalankan buildkite-agent start dengan config di atas, menyala ulang saat gagal, dan menulis log ke file yang sama. Jalankan dari Terminal di desktop Mac:

brew services start buildkite/buildkite/buildkite-agent@3
brew services list | grep buildkite

Di macOS, agen berjalan sebagai pengguna yang menyalakan layanan launchd. Jalankan sebagai akun yang memiliki Xcode dan signing key Anda.

Mulai dengan satu agen per Mac. Buildkite mendokumentasikan pengaturan spawn di file config, dan flag --spawn, untuk menjalankan beberapa agen dari satu layanan. Dua build Xcode sekaligus berebut core dan memori yang sama. Di mesin 16 GB, ukur satu agen dulu, baru coba dua.

5. Pastikan bertahan setelah reboot

Catatan instalasi formula itu sendiri meminta Mac diatur agar login otomatis sebagai pengguna ini. README tap Buildkite menjelaskan untung ruginya. LaunchAgent butuh login, tapi membuat test bisa memakai tool GUI seperti iOS Simulator. Nyalakan login otomatis di System Settings, bagian Users and Groups. Lalu matikan sleep, reboot, dan cek daftar agen.

sudo pmset -a sleep 0
sudo shutdown -r now

Simpan plist di folder LaunchAgents di dalam folder home Anda, tempat Homebrew menaruhnya. Di macOS 27, kami melihat plist di /Library/LaunchAgents merusak login otomatis. Lihat login otomatis di Mac headless.

6. Step pipeline untuk Mac

steps:
  - label: ":xcode: iOS tests"
    agents:
      queue: "macos"
    commands:
      - "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"
      - "ditto -c -k --keepParent build/TestResults.xcresult build/TestResults.xcresult.zip"
    artifact_paths:
      - "build/TestResults.xcresult.zip"
    timeout_in_minutes: 30
    retry:
      automatic:
        - exit_status: -1
          limit: 2

Retry dengan exit_status: -1 berasal dari contoh command step di dokumentasi Buildkite. Retry ini mengulang job saat agennya sendiri hilang, bukan saat test gagal.

Error umum dan cara memperbaikinya

• launchctl menampilkan Could not find domain for. Menurut Buildkite, harus ada pengguna yang login di Mac. Login di desktop dan muat layanannya lagi.
• Refusing to load formula ... from untrusted tap. Jalankan brew trust buildkite/buildkite dan pasang lagi.
• Agen tidak mau tersambung. Token-nya salah, atau key queue di tags tidak ada di cluster ini.
• Agen tidak bisa meng-clone. Taruh key di ~/.ssh milik pengguna yang menjalankan agen.
• xcodebuild: error: Existing file at -resultBundlePath. Build memakai ulang checkout. Hapus bundle lebih dulu, seperti di atas.

Untuk upgrade nanti, jalankan brew update && brew upgrade buildkite/buildkite/buildkite-agent@3.

Mengapa Mac khusus membantu

Buildkite dibuat untuk mesin milik Anda sendiri, dan Mac yang permanen menyimpan cache-nya. Dalam benchmark kami dengan aplikasi iOS Wikipedia di Xcode 26.6, job setelah perubahan kecil butuh 27 detik di M6 yang hangat. Runner macos-26 baru yang di-hosting GitHub butuh 269 detik.

Kapan agen hosted Buildkite sudah cukup

Buildkite juga menawarkan agen macOS hosted. Menurut dokumentasinya, yang kami baca pada Oktober 2026, Anda memilihnya saat membuat hosted queue. Jika Anda tidak mau mengurus mesin sama sekali, itu jalan yang lebih sederhana. MacRun juga bukan pilihan tepat jika Anda butuh SLA, IP statis untuk aturan token, atau lebih dari satu region.

Untuk sisi MacRun, lihat sistem CI lain. Untuk apa yang dijalankan di step, lihat panduan pipeline CI/CD iOS.