Menyiapkan fastlane di server build Mac khusus

Yang Anda butuhkan lebih dulu

• Mac dengan Xcode, akses admin, dan Homebrew.
• Agen CI di Mac itu: GitHub Actions, GitLab, Buildkite, Jenkins, atau CircleCI.
• Akun App Store Connect dengan hak untuk membuat API key.
• Repo Git privat untuk match, atau bucket Google Cloud atau S3.

1. Pasang fastlane

Dokumentasi fastlane, yang kami baca pada Oktober 2026, lebih menyukai Bundler. Dokumentasinya mendukung Ruby 3.2 ke atas dan lebih menyukai 3.3 ke atas. Dokumentasinya juga menyarankan agar tidak memakai Ruby bawaan sistem macOS. Pasang Ruby terbaru dengan version manager seperti rbenv. Lalu tambahkan Gemfile ke proyek:

source "https://rubygems.org"

gem "fastlane"

gem install bundler
bundle update
git add Gemfile Gemfile.lock

Bundler mengunci versi fastlane di Gemfile.lock. Setiap mesin dan setiap run CI mendapat versi yang sama. Jalankan sebagai bundle exec fastlane.

Jalan yang lebih sederhana di satu server build adalah Homebrew. Homebrew membawa Ruby-nya sendiri:

brew install fastlane

Pilih satu jalan per proyek. Mencampur keduanya membuat dua versi fastlane berakhir di satu mesin.

2. Buat API key App Store Connect

fastlane menyarankan API key daripada login Apple ID: tanpa prompt two-factor, lebih cepat, dan lebih andal. Di App Store Connect, buka Users and Access, lalu Integrations, lalu App Store Connect API. Buat Team Key. Menurut fastlane, panggilan provisioning butuh team key. Beri peran sekecil mungkin yang masih berfungsi. Catat Issuer ID dan Key ID. Unduh file .p8 segera, karena Apple hanya mengizinkan Anda mengunduhnya sekali.

mkdir -p ~/.appstoreconnect
mv ~/Downloads/AuthKey_ABC123XYZ.p8 ~/.appstoreconnect/
chmod 600 ~/.appstoreconnect/AuthKey_ABC123XYZ.p8

Simpan key di Mac build atau di secret store milik CI Anda. Jangan pernah meng-commit-nya.

3. Siapkan match sekali, dari mesin developer

bundle exec fastlane match init
bundle exec fastlane match development
bundle exec fastlane match appstore

match init menanyakan lokasi penyimpanan sertifikat dan menulis Matchfile. Dua perintah berikutnya membuat sertifikat dan profile, lalu menyimpannya dalam keadaan terenkripsi di penyimpanan itu. Pilih passphrase yang kuat. CI membacanya dari variabel MATCH_PASSWORD.

fastlane menyarankan mode readonly di semua sistem CI. Dengan begitu CI hanya mengunduh yang sudah ada dan tidak pernah membuat atau mencabut apa pun.

4. Tulis lane-nya

default_platform(:ios)

platform :ios do
  lane :test do
    run_tests(
      scheme: "MyApp",
      devices: ["iPhone 17"],
      result_bundle: true
    )
  end

  lane :beta do
    setup_ci
    api_key = app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_filepath: ENV["ASC_KEY_PATH"]
    )
    match(type: "appstore", readonly: is_ci, api_key: api_key)
    increment_build_number(
      build_number: latest_testflight_build_number(api_key: api_key) + 1
    )
    build_app(scheme: "MyApp")
    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: true)
  end
end

setup_ci membuat keychain sementara, mengubah match ke readonly, dan menyiapkan path untuk log dan hasil test. Perintah ini hanya bekerja saat fastlane mendeteksi run CI. Jika run Anda tidak terdeteksi, tambahkan force: true. Melewati build processing membuat job selesai lebih cepat, tapi menurut fastlane itu juga melewati distribusi ke tester eksternal.

5. Panggil dari CI

Semua sistem CI menjalankan baris shell yang sama. Simpan secret di CI Anda, bukan di repo.

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
bundle install
bundle exec fastlane beta
# needs MATCH_PASSWORD, ASC_KEY_ID, ASC_ISSUER_ID and ASC_KEY_PATH set as CI secrets

Di GitHub Actions, baris-baris ini masuk ke step run, dengan secret diteruskan sebagai env. Mac MacRun sudah dilengkapi software runner GitHub Actions. Panduan setup iOS di GitHub Actions kami menunjukkan workflow lengkapnya. Di GitLab, Buildkite, atau CircleCI, taruh baris yang sama di script job. Di Jenkins, pakai step sh.

Bagaimana ini bertahan setelah reboot

fastlane bukan layanan. Ia berjalan di dalam job milik agen CI Anda. Yang harus bertahan setelah reboot adalah agen dan sesi login-nya. Siapkan agen sebagai LaunchAgent dengan login otomatis, seperti di panduan GitLab Runner dan Buildkite kami. Keychain sementara dari setup_ci dibuat ulang di setiap run. Login keychain yang terkunci setelah restart tidak bisa menghentikannya.

Error umum dan cara memperbaikinya

Daftar ini didokumentasikan oleh fastlane.

• Error encoding yang aneh atau crash di CI. fastlane butuh locale UTF-8. Atur LANG dan LC_ALL ke en_US.UTF-8.
• Job tertahan di prompt two-factor. Pakai API key. Dengan Apple ID, atur SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FA agar job langsung gagal, bukan menunggu.
• match mencoba membuat sertifikat baru di CI. Pakai readonly, atau panggil setup_ci lebih dulu.
• match tidak bisa meng-clone repo-nya. GitHub tidak menerima satu deploy key di dua repo. Pakai akun mesin yang hanya bisa membaca, atau git_private_key, atau MATCH_GIT_BASIC_AUTHORIZATION.
• Profile sudah terpasang tapi Xcode tidak melihatnya. Xcode 16 memindahkan folder profile. fastlane mengikuti Xcode yang dipilih, jadi jalankan xcode_select sebelum match di mesin yang punya dua Xcode.

Mengapa Mac khusus membantu

build_app dan run_tests adalah build Xcode. Di mesin yang menyimpan DerivedData dan gem yang sudah terpasang, keduanya jauh lebih cepat. Dalam benchmark kami dengan aplikasi iOS Wikipedia di Xcode 26.6, clean build butuh 86 detik di M6. Di runner macos-26 yang di-hosting GitHub, butuh 183 detik. Job setelah perubahan kecil butuh 27 detik dalam keadaan hangat, dibanding 269 detik dari awal.

Kapan Anda tidak butuh server build

Jika Anda merilis ke TestFlight seminggu sekali, runner hosted atau Xcode Cloud lebih sedikit pekerjaannya. Lihat panduan alternatif Xcode Cloud kami untuk pertimbangan itu. Perhatikan juga apa yang tidak dikerjakan MacRun. Kami tidak mengurus code signing untuk Anda. Anda menjalankan match sendiri, seperti di halaman ini. Kami juga tidak menawarkan SLA.

Siap memakai server build? Halaman harga mendaftar setiap tier, dan dokumentasi setup menunjukkan cara menghubungkannya.