Match (Fastlane): iOS sertifika yönetimi ve geliştirme yapılandırması

Match (Fastlane) Nedir?

Match (Fastlane), iOS geliştirme için Code Signing sertifikalarını ve Provisioning Profillerini merkezi olarak yönetmek üzere tasarlanmış Fastlane ekosisteminin bir bileşenidir. Ekip üyeleri arasında imza senkronizasyonu sorununu çözer ve geliştirici müdahalesi olmadan CI/CD hatlarında sertifika yapılandırmasını otomatikleştirir.

Match olmadan, her ekip üyesi Xcode veya Apple Developer Portal aracılığıyla manuel olarak sertifika oluşturur ve bu da farklı makinelerde derleme sırasında çakışmalara yol açar. Code Signing, iOS uygulamasını kullanıcının cihazına kurulumdan önce yazarlığını ve bütünlüğünü doğrulayan dijital imzalama işlemidir.

Apple Developer Belgelerine (2025) göre, hatalı sertifika yapılandırması, bir uygulamayı App Store'a gönderirken reddedilmenin en yaygın nedenlerinden biridir. Match, sertifikaların geçerliliğini otomatik olarak kontrol eder ve son kullanma tarihleri hakkında uyarır, böylece Apple doğrulama aşamasında derlemenin reddedilme riskini azaltır.

Match'i iki veya daha fazla geliştiricisi olan veya CI/CD hattı bulunan herhangi bir projede kullanın. Bu, yeni bir ekip üyesinin ortam kurulum süresini 30 dakikadan terminalde tek bir komuta indirir.

Match Nasıl Çalışır: Şifrelenmiş Git Deposu

Match mimarisi, iOS ekibinin tüm sertifikaları için tek bir gerçek kaynağı (Single Source of Truth) konsepti üzerine kurulmuştur. Her geliştiricinin anahtar zincirinde yerel depolama yerine Match, tüm sertifikaları kaydetmeden önce her dosyayı şifreleyerek tek bir Git deposunda birleştirir.

Süreç üç aşamadan oluşur. Başlatma aşamasında Match, Apple Developer Portal API'si aracılığıyla gerekli tüm sertifikaları ve profilleri oluşturur. Her dosya, kullanıcı parola ifadesine dayalı bir anahtarla AES-256 algoritması kullanılarak şifrelenir. Şifrelenmiş dosyalar bir Git deposuna kaydedilir ve standart Git push ve pull işlemleriyle uzak sunucuyla senkronize edilir.

Sertifika Şifreleme Mimarisi

Match, sertifikaları ve profilleri şifrelemek için OpenSSL ve kullanıcı parola ifadesinin bir kombinasyonunu kullanır. Erişim anahtarı MATCH_PASSWORD ortam değişkeni aracılığıyla ayarlanır ve depoda saklanmaz, böylece Git sunucusu tehlikeye girse veya depoya herkese açık erişim olsa bile sızıntı önlenir.

Sertifika istendiğinde, Match depodan şifrelenmiş dosyayı indirir, parola ifadesini kullanarak yerel olarak şifresini çözer ve mevcut makinenin Anahtar Zincirine (Keychain) yükler. Derleme tamamlandıktan sonra, sertifikalar Anahtar Zincirinden kaldırılarak kurumsal ortamın güvenlik politikalarına uyulabilir ve sonraki derlemelerde güncel olmayan sertifikaların kullanılması önlenir.

Her sertifika, uygulama tanımlayıcısını, profil türünü ve oluşturma tarihini içeren bir adla kaydedilir. Bu yapı, Match'in sertifika sürümlerini yönetmesine ve gerekirse standart Git revert ve reset komutları aracılığıyla önceki bir duruma dönmesine olanak tanır. Bu, özellikle yanlışlıkla silme veya profilin üzerine yazma durumlarında kullanışlıdır.

Match Kurulumu ve Yapılandırması

Match kurulumu, Ruby paket yöneticisi aracılığıyla Fastlane ile birlikte yapılır: gem install fastlane. Kurulumdan sonra, fastlane match init komutuyla sertifika deposunu başlatın. Bu komut boş bir Git deposu oluşturur ve temel yapılandırma şablonuyla bir Matchfile dosyası oluşturur.

# Match deposu başlatma
fastlane match init

Matchfile ile Yapılandırma

Matchfile dosyası, sertifika deposuna bağlantı için tüm parametreleri içerir: Git deposu URL'si, varsayılan profil türü, uygulama tanımlayıcıları ve Apple Developer kimlik bilgileri. Beş geliştiriciden oluşan bir ekip için tipik yapılandırma örneği:

# Matchfile configuration
git_url("https://github.com/company/certificates.git")
type(:development)
app_identifier(["com.company.app", "com.company.app.extension"])
username("developer@company.com")
team_id("TEAM123456")
git_branch("main")

type parametresi profil türünü belirler: :development geliştirici cihazlarında hata ayıklama için, :appstore App Store'da yayınlama için, :adhoc harici cihazlarda test için ve :enterprise App Store dışında In-House kurumsal dağıtım içindir. Her tür, depoda ayrı bir dizin oluşturarak profilleri hedef derleme senaryosuna göre düzenlemeye olanak tanır.

Match, Apple Developer Portal'da birden çok kimlik doğrulama yöntemini destekler: Apple ID ile iki faktörlü kimlik doğrulama, Uygulamaya Özel Parola (App-Specific Password) ve App Store Connect API anahtarları. CI/CD için API anahtarlarının kullanılması önerilir. Etkileşimli onay kodu girişi gerektirmezler ve geliştirici cihazı değiştiğinde otomatik derlemeleri engellemezler.

Profil Oluşturma ve Senkronizasyon

Matchfile yapılandırmasından sonra, profilleri oluşturmak ve senkronize etmek için fastlane match development veya fastlane match appstore komutunu çalıştırın. Match, Apple Developer Portal API'si aracılığıyla sertifikaları otomatik olarak oluşturur veya günceller ve depoya kaydeder. Apple Developer Portal, sertifikaları, uygulama tanımlayıcılarını ve izin verilen geliştirici cihazlarının listesini yönetmek için Apple'ın web arayüzüdür.

İlk çalıştırmada Match, depoyu şifrelemek için bir parola ifadesi ister. Bu ifade, CI/CD gizli yöneticisinde (GitHub Actions Secrets, GitLab CI Variables veya Jenkins Credentials) saklanmalı ve MATCH_PASSWORD ortam değişkeni aracılığıyla iletilmelidir. Bu olmadan Match, diğer makinelerde veya CI ortamında sertifikaların şifresini çözemez.

Sertifika Yönetimi için Temel Match Komutları

Match arayüzü, sertifikaları ve profilleri oluşturma, güncelleme, senkronize etme ve silme komutlarından oluşur. Her komut, Code Signing yaşam döngüsünde oluşturmadan deponun tamamen temizlenmesine kadar belirli bir eyleme karşılık gelir.

Günlük Çalışma Komutları

fastlane match development komutu, yerel cihazlarda hata ayıklama için Development sertifikalarını ve profillerini indirir veya oluşturur. Provisioning Profile, geliştirici sertifikasını uygulama tanımlayıcısına ve kurulum için izin verilen cihazların listesine bağlayan Apple'ın dijital belgesidir.

App Store'da yayınlamak için fastlane match appstore kullanılır. Bu komut Distribution sertifikaları ve AppStore profilleri oluşturur. fastlane match adhoc harici cihazlarda test için profiller oluştururken fastlane match enterprise In-House kurumsal uygulamalar için kullanılır.

# Hata ayıklama için Development profilleri oluşturma
fastlane match development

# Yayın için AppStore profilleri oluşturma
fastlane match appstore

# Mevcut manuel sertifikaları içe aktarma
fastlane match import

fastlane match import komutu, mevcut sertifikaları depoya eklemeye olanak tanır. Manuel yönetimden Match'e geçiş yaparken kullanışlıdır. --readonly parametresi, depodaki tüm değişiklikleri engeller. Bu, hattın sertifikaları ve profilleri otomatik olarak oluşturmaması veya silmemesi gereken CI ortamı için kritiktir.

Depoyu tamamen temizlemek için fastlane match nuke komutu kullanılır. Git deposundaki, Apple Developer Portal'daki ve yerel makinedeki tüm sertifikaları siler. Bu, proje için Code Signing durumunun tamamen sıfırlanmasıdır. Komut yalnızca kritik çakışmalarda veya yeni bir Apple Developer hesabına geçiş yaparken kullanılır.

Match'in CI/CD Hattına Entegrasyonu

CI/CD entegrasyonu Match'in temel avantajlarından biridir. GitHub Actions, GitLab CI, Bitrise veya Jenkins hatlarında Match, geliştirici müdahalesi olmadan doğru sertifikaları otomatik olarak indirir ve yükler. Bu, commit'ten nihai IPA'ya kadar iOS uygulamasının tamamen otomatik derlenmesini ve imzalanmasını sağlar.

GitHub Actions için tipik bir yapılandırma, Fastlane kurulumu, MATCH_PASSWORD ortam değişkeninin ayarlanması ve Match'in --readonly bayrağıyla çalıştırılmasını içerir. GitHub Actions, depodaki olaylara dayalı olarak kod derleme, test etme ve yayınlamayı otomatikleştiren GitHub'ın CI/CD platformudur.

# CI ortamına Fastlane kurulumu
gem install fastlane --no-document

# Match'i değişiklik hakkı olmadan salt okunur modda çalıştırma
fastlane match development --readonly

CI'da Match'i çalıştırmadan önce sertifika deposuna erişimi yapılandırmanız gerekir. Fastlane, Matchfile'daki git_url parametresine göre depoyu otomatik olarak kopyalar. Depoya erişim, CI sisteminin sırlarına eklenen bir SSH anahtarı veya kişisel erişim belirteci (personal access token) aracılığıyla yapılandırılır. Bu, sertifikaların herkese açık erişim yoluyla tehlikeye girmemesini sağlar.

CI sağlayıcınızın sırlarında MATCH_PASSWORD ve FASTLANE_APPLE_API_KEY ortam değişkenlerini yapılandırın. App Store Connect API anahtarı, Match'in iki faktörlü kimlik doğrulama olmadan Apple Developer Portal'da kimlik doğrulaması yapmasına olanak tanır, böylece otomatik derlemelerde etkileşimli istemler ortadan kalkar ve hattın engellenmesi önlenir.

Match Kullanırken Sık Karşılaşılan Hatalar

Match doğru yapılandırılmış olsa bile, sertifika sürelerinin dolması, profil çakışmaları veya hatalı ortam yapılandırmasıyla ilgili hatalar oluşabilir. Sorun teşhisi, komut günlüklerinin analizine ve sertifika Git deposunun güncel durumunun kontrol edilmesine dayanır.

En yaygın hata “You need to provide a password for Match”, MATCH_PASSWORD ortam değişkeninin makinede veya CI ortamında ayarlanmaması durumunda oluşur. Çözüm: MATCH_PASSWORD'u sistem ortam değişkenlerine ekleyin veya Match komutunu çalıştırırken parolayı --keychain_password parametresi aracılığıyla iletin.

İkinci en yaygın sorun, AdHoc profiline yeni bir cihaz eklenirken sertifika çakışmasıdır. fastlane match adhoc --force komutuyla yeni cihazları hesaba katarak profilleri yeniden oluşturarak çözülür. Apple Developer sertifikaları bir yıl geçerlidir, ardından bu sertifikaları kullanan derlemeler App Store Connect tarafından reddedilir. Match, sürenin dolmasına 30 gün kala uyarır.

“Multiple matches found for...” hatası durumunda, depoda aynı sertifikanın birden çok sürümü bulunur. Depoyu tamamen temizlemek ve Apple Developer Portal'daki tüm sertifikaları silmek için fastlane match nuke komutunu kullanın. Temizlikten sonra sıfırdan oluşturma yapın; bu, yinelenen veya çakışan sürümler olmadan tutarlı bir profil durumu sağlar.