Build Number — nedir, parametre değeri ve artırma

Build Number Nedir

Build Number, bir mobil uygulamanın her derlemesine atanan benzersiz bir tam sayı tanımlayıcısıdır. Uygulama mağazaları, sürüm yeniliğini belirlemek için bunu kullanır — sayı ne kadar yüksekse, derleme o kadar yenidir.

Android'de bu parametreye versionCode denir, iOS'ta — CFBundleVersion. Her iki parametre de yayınlama için zorunludur ve her yeni derlemede monoton bir şekilde artmalıdır.

Google Play Console Help (2025)'e göre, her APK yüklemesinde versionCode kontrol edilir: zaten yayınlanmış sürüme eşit veya daha küçük versionCode'a sahip bir derleme yüklenirse, Google Play dosyayı bir hatayla reddeder.

Build Number'ı iç derleme takibi için kullanın — sorunlu sürümleri hızlı bir şekilde belirlemek için numarayı sürüm kontrol sisteminizdeki commit hash'i ile ilişkilendirin.

Build Number Neden Gereklidir

Build Number, derlenen her uygulama sürümünün net bir şekilde tanımlanması sorununu çözer. Bu olmadan, Version Name değişmemişse hangi derlemenin daha yeni olduğunu belirlemek imkansızdır.

Google Play ve App Store gibi uygulama mağazaları, güncellemeler sırasında çakışmaları çözmek için Build Number kullanır. Bir kullanıcı eski bir sürümün üzerine yeni bir sürüm yüklediğinde, sistem Build Number'ı karşılaştırır ve yalnızca değer daha yüksekse güncelleme sunar.

Bu mekanizma, güncellemelerin doğru şekilde iletilmesi için kritik öneme sahiptir: monoton bir şekilde artan Build Number olmadan, kullanıcılar uygulamanın eski bir sürümünde takılı kalabilir.

Build Number Biçimleri

Build Number, basit bir sıralı sayı (1, 2, 3...) veya ek bilgileri kodlayan bileşik bir sayı olabilir. Bileşik sayılar genellikle derleme tarihini veya CI/CD sistemi derleme numarasını içerir.

Android için versionCode, int türünde bir tam sayıdır ve maksimum değeri 2100000000'dir. iOS için CFBundleVersion, noktalarla ayrılmış üç sayıdan oluşan bir dizedir ve her biri 255'i geçemez.

Apple Developer (2025)'e göre, CFBundleVersion en fazla 3 bileşeni destekler, ancak App Store sürüm karşılaştırması için bunları tek bir sıra sayısı olarak kullanır.

Android'de Build Number

Android'de Build Number, build.gradle dosyasındaki versionCode parametresiyle ayarlanır. Bu, Google Play'de yayınlanan her uygulama sürümü için benzersiz olması gereken bir tam sayıdır.

Parametre android.defaultConfig bloğu içinde bildirilir ve her yeni sürümle birlikte artmalıdır. Google Play, aynı uygulamanın başka bir sürümü için zaten kullanılmış bir versionCode'a sahip APK yüklenmesine izin vermez.

Google Play Developer API (2025)'e göre, versionCode'un maksimum değeri 2100000000'dir. Sınırı tüketmemek için 1'den başlamanız ve her yeni derleme için 1 artırmanız önerilir.

Sürüm numarasını kodlayan bileşik bir versionCode kullanın: Major * 1000000 + Minor * 1000 + Patch — bu, anlamsal sürümle eşleştirmeyi basitleştirir.

Android'de versionCode Sınırlamaları

versionCode'un katı sınırlamaları vardır: 32 bit işaretli bir tam sayıdır, bu nedenle maksimum değer 2100000000'dir. Sınır tüketilirse, uygulama Google Play'de güncellenemez.

Android App Bundle için versionCode ayrıca temel modülde de belirtilir ve her özellik modülünün kendi versionCode'u olabilir. Google Play bunları tek bir doğrulama sisteminde birleştirir.

Bir sürümleme stratejisi seçerken bu sınırlamayı dikkate almak önemlidir — sayının çok hızlı artması uzun vadede sorunlara yol açabilir.

iOS'ta Build Number

iOS'ta Build Number, Info.plist dosyasındaki CFBundleVersion anahtarıyla ayarlanır. Android'in aksine, bu parametre bir dizedir ancak her yeni derlemede artması gerekir.

CFBundleVersion biçimi, noktalarla ayrılmış bir ila üç sayıdan oluşur. Her sayı 255'i geçemez. App Store, karşılaştırma için dizeyi bir sayı dizisi olarak yorumlar: 1.0.1, 1.0.0'dan daha yeni kabul edilir.

Apple Developer Documentation (2025)'e göre, App Store Connect yüklenen her derleme için benzersiz bir CFBundleVersion gerektirir. Zaten kullanılmış bir numaraya sahip bir derleme yüklenirse, sistem onu reddeder.

Her derlemede sayının monoton büyümesini sağlamak için CFBundleVersion'ı agvtool veya Xcode derleme komut dosyaları aracılığıyla yönetin.

Xcode Build Settings ile Entegrasyon

Xcode, Build Settings aracılığıyla CFBundleVersion yönetimine izin verir. “Current Project Version” alanı temel değeri belirler ve Build Phase komut dosyaları bunu otomatik olarak artırabilir.

CI/CD için, Info.plist'ten geçerli sürümü okuyan ve belirtilen değer kadar artıran fastlane eklentisi increment_build_number'ı kullanın. Bu, her derlemenin benzersizliğini garanti eder.

Bu yaklaşım, Build Number yönetimini tamamen otomatikleştirir ve sürüm hazırlığı sırasında insan hatalarını ortadan kaldırır.

Build Number Otomatik Artırma

Build Number'ın otomatik artırılması, modern CI/CD hatlarında standart bir uygulamadır. Derleme numarasının manuel olarak artırılması, yayınlama sırasında hatalara ve çakışmalara yol açar.

GitHub Actions, GitLab CI ve Jenkins, derleme numarasıyla birlikte yerleşik değişkenler sağlar. Bu değişkenler, Build Number'ın otomatik olarak değiştirilmesi için Gradle veya Xcode komut dosyalarında kullanılır.

GitLab CI Documentation (2025)'e göre, CI_PIPELINE_IID değişkeni her hat için benzersiz bir numarayı garanti eder ve bu da onu Build Number olarak kullanım için ideal kılar.

CI/CD düzeyinde otomatik artırmayı yapılandırın — bu, sürüm dalındaki her commit için Build Number'ı manuel olarak değiştirme ihtiyacını ortadan kaldırır.

Popüler Otomasyon Araçları

GitHub Actions, her hat çalıştırmasında otomatik olarak artan yerleşik run_number değişkenini destekler. Değer, versionCode aracılığıyla Gradle'a iletilebilir.

Jenkins, tüm derleme aşamalarında kullanılabilen BUILD_NUMBER değişkenini kullanır. Xcode projeleri için Jenkins, bu numarayla agvtool'ı çalıştırır.

Ek yapılandırmayı en aza indirmek için yığınınıza entegre edilmiş aracı seçin.

Build Number ve Version Name

Build Number ve Version Name bir çift olarak çalışır: ilki makineler için, ikincisi insanlar içindir. Build Number teknik benzersizliği sağlar, Version Name kullanıcı dostu anlam sağlar.

Android'de bu iki parametre bağımsızdır: versionCode, versionName'i değiştirmeden artabilir (örneğin, bir derleme hatasını düzeltmek için). iOS'ta CFBundleVersion da CFBundleShortVersionString'e bağlı değildir.

Stack Overflow Developer Survey (2024)'e göre, ekiplerin %82'si otomatik Build Number artırma kullanıyor, ancak yalnızca %45'i Version Name güncellemelerini otomatikleştiriyor — bu, sürüm hatalarının yaygın nedenlerinden biridir.

Version Name değişmiyorsa bile her derlemede Build Number'ı artırın — bu, uygulama mağazalarında güncelleme mekanizmasının doğru çalışmasını sağlar.

Build Number için En İyi Uygulamalar

versionCode'a 1'den başlayın ve her derleme için 1 artırın. iOS için CFBundleVersion ile benzer bir yaklaşım kullanın. Kesinlikle gerekli olmadıkça bileşik sayılardan kaçının — basit bir sıralı sayının takibi daha kolaydır.

Build Number'ı CI/CD sistemi derleme numarasına bağlayın — bu, bir hatadan belirli bir commit'e kadar izlemeyi basitleştirir. Derleme numarası ve sürümüyle Git etiketi, sürüm yönetimi için en iyi uygulamadır.

Build Number Yapılandırma Örnekleri

Kod örnekleri, her iki platformda da otomatik Build Number artırmanın nasıl yapılandırılacağını gösterir.

CI Değişkeniyle Gradle'da versionCode

Android'de versionCode, bir CI/CD ortam değişkeni aracılığıyla ayarlanabilir. Değişken ayarlanmamışsa, varsayılan bir değer kullanılır.

android {
    defaultConfig {
        versionCode System.getenv("CI_PIPELINE_ID")?.toInteger() ?: 1
        versionName "1.2.0"
    }
}

versionCode, değerini CI/CD değişkeninden alır ve bu da hattaki her derleme için numaranın benzersizliğini garanti eder.

agvtool ile CFBundleVersion Artırma

iOS'ta, Xcode Command Line Tools içine yerleşik olan agvtool, Build Number'ın otomatik olarak artırılması için kullanılır.

# Derleme numarasını 1 artır
xcrun agvtool next-version -all

# Belirli bir derleme numarası ayarla
xcrun agvtool new-version -all "3.0.1"

Bayrak -all, projedeki tüm hedeflerde sürümü günceller ve ana uygulama ile uzantılar arasında değerlerin senkronizasyonunu sağlar.

Otomasyon için Fastlane

Fastlane, mobil uygulama derlemelerini otomatikleştirmek için popüler bir araçtır. increment_build_number eklentisi, Build Number'ı otomatik olarak artırır.

increment_build_number(
    build_number: ENV["BUILD_NUMBER"] ||
                 latest_testflight_build_number + 1
)

Fastlane, herhangi bir CI/CD sistemiyle entegre olur ve hem Android hem de iOS projelerini destekler.