Pilot (Fastlane): temel kavramlar, TestFlight ve mobil projeler için build yönetimi

Pilot (Fastlane) Nedir?

Pilot (Fastlane), mobil uygulamaların beta testi için Apple'ın platformu olan TestFlight ile çalışmayı otomatikleştiren Fastlane ekosisteminin bir bileşenidir. Pilot, build yükleme, testçi ekleme, grup yönetimi ve build durumu takibi gibi tüm rutin işlemleri üstlenir.

Pilot olmadan, beta dağıtım süreci şöyle görünür: geliştirici manuel olarak App Store Connect'i açar, uygulamayı seçer, Xcode Organizer aracılığıyla IPA'yı yükler, bir testçi grubu yapılandırır ve davetiyeler gönderir. TestFlight, App Store'da resmi yayınlanmadan önce uygulamaların beta sürümlerini testçilere dağıtmak için Apple'ın hizmetidir.

App Store Connect Help (2025)'e göre, harici testçiler ilk build kurulumundan önce Beta App Review sürecinden geçmelidir — bu 1 ila 48 saat sürer. Pilot, inceleme durumunu otomatik olarak takip eder ve build harici testçi gruplarına dağıtıma hazır olduğunda ekibi bilgilendirir.

Pilot'u, testçilere düzenli beta build teslimi gerektiren herhangi bir projede kullanın — iOS CI/CD hatları için standart bir araçtır ve öngörülebilir bir teslim süreci sağlar.

TestFlight için Pilot'un Ana İşlevleri

Pilot'un işlevselliği, beta build yönetiminin tüm yaşam döngüsünü kapsar: ikili dosya yüklemeden testçilere yeni sürüm hakkında bildirim göndermeye kadar. Her işlev, öngörülebilir davranış ve her adımın ayrıntılı günlüğü ile ayrı bir komut olarak uygulanır.

TestFlight'a Build Yükleme

fastlane pilot upload komutu, IPA dosyasını App Store Connect'e yükler ve TestFlight'ta yeni bir build oluşturur. Pilot, ikili dosyanın geçerliliğini, sürüm uyumluluğunu ve uygulama tanımlayıcısını otomatik olarak kontrol eder. App Store Connect, build yükleme, meta veriler, analizler ve satış raporları dahil olmak üzere uygulamaları yönetmek için Apple'ın platformudur.

Yüklemeden sonra Pilot, Apple'ın ikili dosyayı işlemesini bekler — süreç build boyutuna bağlı olarak 5 ila 30 dakika sürer. Beklerken Pilot, mevcut işlem durumu hakkında bilgi içeren bir ilerleme çubuğu görüntüler: Processing, Validating veya Ready. Başarılı işlemin ardından build, testçi gruplarına atanmak üzere kullanılabilir hale gelir.

Testçi Gruplarını Yönetme

Pilot, hem dahili hem de harici testçi gruplarının yönetimini destekler. Dahili testçiler, Beta App Review'dan geçmeden build'lere anında erişim sağlayan Apple Developer ekibinizin üyeleridir. Harici testçiler, e-posta yoluyla davet edilen ve ilk kurulumdan önce inceleme onayı gerektiren kullanıcılardır.

fastlane pilot add komutu, e-posta veya Apple ID ile bir gruba yeni testçiler ekler. Pilot otomatik olarak davetiyeler gönderir ve testçinin daveti kabul edip etmediğini kontrol eder. Toplu ekleme için, --testers_file_path parametresini kullanarak bir dosyadan e-posta listesi iletebilirsiniz; bu, yüzlerce katılımcıdan oluşan bir testçi grubu oluştururken kullanışlıdır.

# TestFlight'a yeni bir build yükleme
fastlane pilot upload --ipa "build/MyApp.ipa"

# Bir gruba testçi ekleme
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

Pilot Kurulumu ve Yapılandırması

Pilot yapılandırması ayrı bir yapılandırma dosyası gerektirmez — ayarlar Appfile (ortak Fastlane dosyası) veya komut satırı argümanları aracılığıyla iletilir. Ana parametreler, uygulamanın apple_id'sini, app_identifier'ını, team_id'sini ve App Store Connect API'sine erişim için kimlik bilgilerini içerir.

Kimlik doğrulama için Pilot, App Store Connect API Key (önerilen yöntem) veya Apple ID iki faktörlü kimlik doğrulamayı kullanır. App Store Connect API Key, App Store Connect'te oluşturulan ve etkileşimli olarak şifre ve onay kodu girmeden API ile etkileşime izin veren bir erişim anahtarıdır.

# Appfile — Fastlane ortak yapılandırması
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Pilot için ortam değişkenleri
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

app_identifier parametresi, uygulamanın Bundle Identifier'ını tanımlar ve Xcode projesinde ve App Store Connect'te belirtilen tanımlayıcıyla eşleşmelidir. apple_id parametresi, iki faktörlü şemada kimlik doğrulama için kullanılır ve team_id — hesap birden çok Apple Developer ekibine bağlıysa geliştirme ekibini seçmek için kullanılır.

Pilot'un çalışması için CI/CD ortamında App Store Connect API Key'i yapılandırmanız gerekir. Anahtar, App Store Connect → Users and Access → Keys → Generate API Key'de oluşturulur. .p8 dosyasını CI sistemi sırlarında saklayın ve APP_STORE_CONNECT_API_KEY_PATH ortam değişkeni veya Pilot komutlarında --api_key_path parametresi aracılığıyla yolu belirtin.

Build Yönetimi için Pilot Komutları

Pilot komut seti, build yükleme, testçi yönetimi, durum görüntüleme ve meta veri takibi dahil tüm TestFlight senaryolarını kapsar. Her komut, CI/CD betiklerinde daha fazla işleme için yapılandırılmış JSON çıktısı döndürür.

Build Durumlarını Görüntüleme

fastlane pilot builds komutu, sürüm, işlem durumu ve yükleme tarihi ile birlikte tüm uygulama build'lerinin bir listesini görüntüler. Build durumu şunlardan biri olabilir: Processing — Apple ikili dosyayı işliyor, Ready — build dağıtım için hazır, Rejected — doğrulama hataları nedeniyle build reddedildi.

# TestFlight'taki tüm build'lerin listesini görüntüleme
fastlane pilot builds

# Bir testçi grubuna build atama
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# Belirli bir build hakkında bilgi görüntüleme
fastlane pilot build_info --build_number 42

fastlane pilot distribute komutu, build'i belirtilen testçi gruplarına atar ve bildirimler gönderir. --notify parametresi, yeni bir kullanılabilir build hakkında testçilere e-posta bildirimleri göndermeyi etkinleştirir — bu, beta testçilerini test sürecine dahil etmek ve geri bildirimi hızlandırmak için kritiktir.

Build meta verilerini yönetmek için, yeni sürümdeki değişikliklerin açıklama metnini ayarlayan --changelog parametresini kullanın. Bu metin, TestFlight uygulamasındaki test davetiyesinde testçilere gösterilir. Her build'de önemli değişiklikleri, düzeltilen hataları ve yeni özellikleri belirtmeniz önerilir.

Pilot'u CI/CD Hattına Entegre Etme

CI/CD'de Pilot, iOS uygulama teslim hattının son aşamasıdır. Gym IPA'yı oluşturduktan ve testler geçildikten sonra Pilot, build'i TestFlight'a yükler ve testçi gruplarına dağıtır. Bu, QA ekiplerinin depoya bir commit'ten dakikalar sonra yeni uygulama sürümünü almasını sağlar.

Tipik bir iOS CI/CD hattı şu sırayı içerir: Match (sertifikalar), Gym (IPA build), Pilot (TestFlight'a yükleme ve dağıtım). Her aşama bir öncekine bağlıdır ve yalnızca geçerli ve imzalı build'lerin testçilere teslim edilmesini sağlar.

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

upload komutundaki skip_waiting parametresi, bir CI görevi içinde Apple'ın ikili dosya işlemesinin tamamlanmasını beklememeyi sağlar — Pilot yükleme isteği gönderir, build tanımlayıcısını alır ve sonlanır. Bu, işlem 30 dakika kadar sürebileceğinden CI runner'da beklemeyle harcanmayarak hattı hızlandırır.

Pilot'un CI'da doğru çalışması için App Store Connect API anahtarını yapılandırmanız gerekir. .p8 anahtar dosyasını CI sisteminin güvenli deposunda saklayın ve yolu APP_STORE_CONNECT_API_KEY_PATH ortam değişkeni aracılığıyla iletin. Pilot bu anahtarı, otomatik senaryolar için kritik olan iki faktörlü kimlik doğrulama olmadan API'de kimlik doğrulamak için kullanır.

Pilot ile Çalışırken Sık Karşılaşılan Sorunlar

Pilot'u kullanırken geliştiriciler en sık kimlik doğrulama hataları, yanlış uygulama yapılandırması ve Apple tarafında ikili dosya işleme sorunlarıyla karşılaşır. Pilot sorun teşhisi, pilot builds komutu aracılığıyla App Store Connect'te build durumunu kontrol ederek başlar.

“Your app is not available for testing in TestFlight” hatası, uygulama App Store Connect'te test için yapılandırılmadığında oluşur. Çözüm: App Store Connect'te TestFlight bölümünü açın, uygulama için testi etkinleştirin ve Export Compliance'ın şifreleme türünüz için doğru doldurulduğundan emin olun.

“Missing iOS Distribution signing identity” hatası, Anahtarlık'ta Distribution sertifikasının olmadığını gösterir. Çözüm: Pilot'u çağırmadan önce doğru sertifikayı indirmek için Match'i çalıştırın. Bir Distribution sertifikası, Development'dan farklıdır — TestFlight veya App Store aracılığıyla dağıtım amaçlı build'leri imzalamak için kullanılır.

“Invalid Provisioning Profile” hatasında, build seçilen dışa aktarma yöntemi için yanlış bir profil içerir. Çözüm: Gym'in Match'teki profil türüyle eşleşen doğru export_method'u kullandığını kontrol edin. Build bir development profiliyle oluşturulmuşsa, Pilot onu TestFlight'a yükleyemez — bir app-store veya ad-hoc profili gereklidir.