Pilot (Fastlane): konsep kunci, TestFlight dan manajemen build untuk proyek mobile

Apa itu Pilot (Fastlane)?

Pilot (Fastlane) — adalah komponen ekosistem Fastlane untuk mengotomatiskan pekerjaan dengan TestFlight — platform Apple untuk pengujian beta aplikasi mobile. Pilot mengambil alih semua operasi rutin: mengunggah build, menambahkan penguji, mengelola grup, dan melacak status build.

Tanpa Pilot, proses distribusi versi beta terlihat seperti ini: pengembang secara manual membuka App Store Connect, memilih aplikasi, mengunggah IPA melalui Xcode Organizer, mengonfigurasi grup penguji, dan mengirim undangan. TestFlight — adalah layanan Apple untuk mendistribusikan versi beta aplikasi di antara penguji sebelum rilis resmi di App Store.

Menurut App Store Connect Help (2025), penguji eksternal harus melalui proses Beta App Review sebelum instalasi pertama build — ini memakan waktu 1 hingga 48 jam. Pilot secara otomatis melacak status review dan memberi tahu tim ketika build siap didistribusikan ke grup penguji eksternal.

Gunakan Pilot di proyek mana pun yang memerlukan pengiriman build beta secara teratur ke penguji — ini adalah alat standar untuk pipeline CI/CD aplikasi iOS yang memastikan proses pengiriman yang dapat diprediksi.

Fungsi utama Pilot untuk TestFlight

Fungsionalitas Pilot mencakup siklus hidup lengkap manajemen build beta: dari mengunggah file biner hingga memberi tahu penguji tentang versi baru. Setiap fungsi diimplementasikan sebagai perintah terpisah dengan perilaku yang dapat diprediksi dan pencatatan detail setiap langkah.

Mengunggah build ke TestFlight

Perintah fastlane pilot upload mengunggah file IPA ke App Store Connect dan membuat build baru di TestFlight. Pilot secara otomatis memeriksa validitas file biner, kesesuaian versi, dan identifikasi aplikasi. App Store Connect — adalah platform Apple untuk mengelola aplikasi, termasuk mengunggah build, metadata, analitik, dan laporan penjualan.

Setelah diunggah, Pilot menunggu pemrosesan file biner oleh Apple — proses ini memakan waktu 5 hingga 30 menit tergantung ukuran build. Selama menunggu, Pilot menampilkan bilah kemajuan dengan informasi tentang status pemrosesan saat ini: Processing, Validating, atau Ready. Setelah pemrosesan berhasil, build tersedia untuk ditetapkan ke grup penguji.

Mengelola grup penguji

Pilot mendukung manajemen grup penguji internal maupun eksternal. Penguji internal — adalah anggota tim Apple Developer Anda yang mendapatkan akses ke build secara instan, tanpa melalui Beta App Review. Penguji eksternal — adalah pengguna yang diundang melalui email, yang memerlukan persetujuan review sebelum instalasi pertama.

Perintah fastlane pilot add menambahkan penguji baru ke grup melalui email atau Apple ID. Pilot secara otomatis mengirim undangan dan memeriksa apakah penguji telah menerima undangan. Untuk penambahan massal, Anda dapat meneruskan daftar email dari file melalui parameter --testers_file_path, yang nyaman untuk pengumpulan awal grup penguji dengan ratusan peserta.

# Mengunggah build baru ke TestFlight
fastlane pilot upload --ipa "build/MyApp.ipa"

# Menambahkan penguji ke grup
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

Pengaturan dan konfigurasi Pilot

Konfigurasi Pilot tidak memerlukan file konfigurasi terpisah — pengaturan diteruskan melalui Appfile (file Fastlane bersama) atau argumen baris perintah. Parameter utama meliputi apple_id aplikasi, app_identifier, team_id, dan kredensial untuk mengakses App Store Connect API.

Untuk autentikasi, Pilot menggunakan App Store Connect API Key (metode yang direkomendasikan) atau autentikasi dua faktor Apple ID. App Store Connect API Key — adalah kunci akses yang dibuat di App Store Connect dan memungkinkan interaksi dengan API tanpa memasukkan kata sandi dan kode konfirmasi secara interaktif.

# Appfile — konfigurasi umum Fastlane
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Variabel lingkungan untuk Pilot
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

Parameter app_identifier menentukan Bundle Identifier aplikasi, yang harus cocok dengan pengenal yang ditentukan di proyek Xcode dan App Store Connect. Parameter apple_id digunakan untuk autentikasi dalam skema dua faktor, dan team_id — untuk memilih tim pengembangan jika akun terhubung ke beberapa tim Apple Developer.

Untuk pengoperasian Pilot, App Store Connect API Key harus dikonfigurasi di lingkungan CI/CD. Kunci dibuat di App Store Connect → Users and Access → Keys → Generate API Key. Simpan file .p8 di rahasia sistem CI dan tunjukkan jalurnya melalui variabel lingkungan APP_STORE_CONNECT_API_KEY_PATH atau parameter --api_key_path di perintah Pilot.

Perintah Pilot untuk mengelola build

Kumpulan perintah Pilot mencakup semua skenario bekerja dengan TestFlight: mengunggah build, mengelola penguji, melihat status, dan melacak metadata. Setiap perintah mengembalikan output JSON terstruktur untuk pemrosesan lebih lanjut dalam skrip CI/CD.

Melihat status build

Perintah fastlane pilot builds menampilkan daftar semua build aplikasi dengan versi, status pemrosesan, dan tanggal unggah. Status build dapat berupa salah satu dari: Processing — Apple memproses file biner, Ready — build tersedia untuk distribusi, Rejected — build ditolak karena kesalahan validasi.

# Melihat daftar semua build di TestFlight
fastlane pilot builds

# Menetapkan build ke grup penguji
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# Melihat informasi tentang build tertentu
fastlane pilot build_info --build_number 42

Perintah fastlane pilot distribute menetapkan build ke grup penguji yang ditentukan dan mengirim pemberitahuan. Parameter --notify mengaktifkan pengiriman pemberitahuan email kepada penguji tentang build baru yang tersedia — ini penting untuk melibatkan penguji beta dalam proses pengujian dan mempercepat umpan balik.

Untuk mengelola metadata build, digunakan parameter --changelog, yang mengatur teks deskripsi perubahan di versi baru. Teks ini ditampilkan kepada penguji dalam undangan pengujian di aplikasi TestFlight. Disarankan untuk menyebutkan perubahan utama, bug yang diperbaiki, dan fitur baru di setiap build.

Integrasi Pilot dalam pipeline CI/CD

Pilot dalam CI/CD — adalah tahap akhir dari pipeline pengiriman aplikasi iOS. Setelah Gym membangun IPA dan pengujian berhasil, Pilot mengunggah build ke TestFlight dan mendistribusikannya ke grup penguji. Ini memungkinkan tim QA menerima versi baru aplikasi beberapa menit setelah commit di repositori.

Pipeline CI/CD iOS yang khas mencakup urutan: Match (sertifikat), Gym (membangun IPA), Pilot (mengunggah ke TestFlight dan distribusi). Setiap tahap bergantung pada tahap sebelumnya, yang menjamin pengiriman hanya build yang valid dan ditandatangani ke penguji.

# Pipeline lengkap di Fastfile
lane :beta do
    match(type: :appstore)
    gym(scheme: "MyApp", export_method: "app-store")
    pilot("build/MyApp.ipa", groups: ["QA", "PM"])
end

Parameter skip_waiting dalam perintah upload memungkinkan untuk tidak menunggu penyelesaian pemrosesan file biner oleh Apple dalam tugas CI — Pilot mengirim permintaan unggah, menerima ID build, dan menyelesaikan pekerjaannya. Ini mempercepat pipeline karena pemrosesan dapat memakan waktu hingga 30 menit yang tidak terbuang untuk menunggu di runner CI.

Untuk pengoperasian Pilot yang benar di CI, kunci API App Store Connect harus dikonfigurasi. Simpan file kunci .p8 di penyimpanan aman sistem CI dan teruskan jalurnya melalui variabel lingkungan APP_STORE_CONNECT_API_KEY_PATH. Pilot menggunakan kunci ini untuk autentikasi di API tanpa autentikasi dua faktor, yang penting untuk skenario otomatis.

Masalah umum saat bekerja dengan Pilot

Saat menggunakan Pilot, pengembang paling sering mengalami kesalahan autentikasi, konfigurasi aplikasi yang salah, dan masalah pemrosesan file biner oleh Apple. Diagnostik masalah Pilot dimulai dengan memeriksa status build di App Store Connect melalui perintah pilot builds.

Kesalahan «Your app is not available for testing in TestFlight» terjadi ketika aplikasi tidak dikonfigurasi untuk pengujian di App Store Connect. Solusi: buka bagian TestFlight di App Store Connect, aktifkan pengujian untuk aplikasi, dan pastikan Export Compliance diisi dengan benar untuk jenis enkripsi Anda.

Kesalahan «Missing iOS Distribution signing identity» menunjukkan tidak adanya sertifikat Distribution di Keychain. Solusi: jalankan Match untuk memuat sertifikat yang benar sebelum memanggil Pilot. Sertifikat Distribution berbeda dari Development — digunakan untuk menandatangani build yang ditujukan untuk distribusi melalui TestFlight atau App Store.

Pada kesalahan «Invalid Provisioning Profile» build berisi profil yang salah untuk metode ekspor yang dipilih. Solusi: periksa apakah Gym menggunakan export_method yang benar sesuai dengan jenis profil di Match. Jika build dibangun dengan profil pengembangan, Pilot tidak akan dapat mengunggahnya ke TestFlight — diperlukan profil app-store atau ad-hoc.