Build Number — apa itu, arti parameter dan increment

Apa itu Build Number

Build Number — adalah pengidentifikasi bilangan bulat unik yang diberikan kepada setiap build aplikasi mobile. Toko aplikasi menggunakannya untuk menentukan kebaruan versi — semakin besar angkanya, semakin baru build tersebut.

Di Android parameter ini disebut versionCode, di iOS — CFBundleVersion. Kedua parameter wajib untuk publikasi dan harus meningkat secara monoton dengan setiap build baru.

Menurut data Google Play Console Help (2025), versionCode diperiksa pada setiap upload APK: jika build yang diupload memiliki versionCode lebih kecil atau sama dengan yang sudah dipublikasikan, Google Play menolak file dengan kesalahan.

Gunakan Build Number untuk pelacakan build internal — hubungkan nomor dengan commit hash di sistem kontrol versi untuk mengidentifikasi rilis bermasalah dengan cepat.

Mengapa Build Number diperlukan

Build Number memecahkan masalah identifikasi unik dari setiap versi aplikasi yang dibangun. Tanpanya, tidak mungkin menentukan build mana yang lebih baru jika Version Name tidak berubah.

Toko aplikasi seperti Google Play dan App Store menggunakan Build Number untuk menyelesaikan konflik saat pembaruan. Jika pengguna menginstal versi baru di atas versi lama, sistem membandingkan Build Number dan menawarkan pembaruan hanya jika nilainya lebih besar.

Mekanisme ini sangat penting untuk pengiriman pembaruan yang benar: tanpa Build Number yang meningkat secara monoton, pengguna bisa terjebak di versi lama aplikasi.

Format Build Number

Build Number bisa berupa angka berurutan sederhana (1, 2, 3...) atau gabungan yang mengkodekan informasi tambahan. Nomor gabungan sering menyertakan tanggal build atau nomor build dari sistem CI/CD.

Untuk Android versionCode adalah bilangan bulat tipe int, nilai maksimum — 2100000000. Untuk iOS CFBundleVersion adalah string dari tiga angka yang dipisahkan titik, masing-masing tidak lebih dari 255.

Menurut data Apple Developer (2025), CFBundleVersion mendukung hingga 3 komponen, tetapi App Store menggunakannya sebagai satu nomor urut untuk membandingkan versi.

Build Number di Android

Di Android Build Number diatur dengan parameter versionCode di file build.gradle. Ini adalah bilangan bulat yang harus unik untuk setiap versi aplikasi yang dipublikasikan di Google Play.

Parameter dideklarasikan di dalam blok android.defaultConfig dan harus meningkat dengan setiap rilis baru. Google Play tidak mengizinkan upload APK dengan versionCode yang sudah digunakan untuk versi lain dari aplikasi yang sama.

Menurut data Google Play Developer API (2025), nilai maksimum versionCode adalah 2100000000. Disarankan untuk memulai dari 1 dan meningkat 1 untuk setiap build baru untuk menghindari kehabisan batas.

Gunakan versionCode gabungan yang mengkodekan nomor versi: Major * 1000000 + Minor * 1000 + Patch — ini menyederhanakan pemetaan ke versi semantik.

Batasan versionCode di Android

versionCode memiliki batasan ketat: ini adalah bilangan bulat 32-bit dengan tanda, jadi nilai maksimumnya adalah 2100000000. Saat batas habis, aplikasi tidak akan bisa diperbarui di Google Play.

Untuk Android App Bundle, versionCode juga ditentukan di modul base, dan setiap modul fitur dapat memiliki versionCode sendiri. Google Play menggabungkannya dalam satu sistem verifikasi.

Batasan ini penting untuk dipertimbangkan saat memilih strategi versi — pertumbuhan angka yang terlalu cepat dapat menyebabkan masalah dalam jangka panjang.

Build Number di iOS

Di iOS Build Number diatur dengan kunci CFBundleVersion di file Info.plist. Berbeda dengan Android, parameter ini adalah string, tetapi juga harus meningkat dengan setiap build baru.

Format CFBundleVersion — dari satu hingga tiga angka yang dipisahkan titik. Setiap angka tidak boleh melebihi 255. App Store menginterpretasikan string sebagai urutan angka untuk perbandingan: 1.0.1 dianggap lebih baru dari 1.0.0.

Menurut data Apple Developer Documentation (2025), App Store Connect memerlukan keunikan CFBundleVersion untuk setiap build yang diupload. Jika build dengan nomor yang sudah digunakan diupload, sistem akan menolaknya.

Kelola CFBundleVersion melalui agvtool atau skrip build Xcode untuk menjamin peningkatan monoton nomor di setiap build.

Integrasi dengan Xcode Build Settings

Xcode memungkinkan pengelolaan CFBundleVersion melalui pengaturan Build Settings. Bidang “Current Project Version” menetapkan nilai dasar, dan skrip Build Phase dapat meningkatkannya secara otomatis.

Untuk CI/CD gunakan plugin fastlane increment_build_number, yang membaca versi saat ini dari Info.plist dan meningkatkannya dengan nilai tertentu. Ini menjamin keunikan setiap build.

Pendekatan ini sepenuhnya mengotomatiskan manajemen Build Number dan menghilangkan kesalahan manusia saat persiapan rilis.

Increment Otomatis Build Number

Increment otomatis Build Number adalah praktik standar dalam pipeline CI/CD modern. Peningkatan nomor build secara manual menyebabkan kesalahan dan konflik saat publikasi.

GitHub Actions, GitLab CI dan Jenkins menyediakan variabel bawaan dengan nomor build. Variabel ini digunakan dalam skrip Gradle atau Xcode untuk pengisian otomatis Build Number.

Menurut data GitLab CI Documentation (2025), variabel CI_PIPELINE_IID menjamin nomor unik untuk setiap pipeline, yang ideal untuk digunakan sebagai Build Number.

Konfigurasikan increment otomatis di tingkat CI/CD — ini akan menghilangkan kebutuhan mengubah Build Number secara manual pada setiap commit ke cabang rilis.

Alat Otomatisasi Populer

GitHub Actions mendukung variabel bawaan run_number, yang secara otomatis meningkat untuk setiap eksekusi pipeline. Nilainya dapat diteruskan ke Gradle melalui versionCode.

Jenkins menggunakan variabel BUILD_NUMBER, yang tersedia di semua tahap build. Untuk proyek Xcode, Jenkins menjalankan agvtool dengan nomor ini.

Pilih alat yang terintegrasi dengan tumpukan teknologi Anda untuk meminimalkan konfigurasi tambahan.

Build Number dan Version Name

Build Number dan Version Name bekerja sebagai pasangan: yang pertama — untuk mesin, yang kedua — untuk manusia. Build Number memberikan keunikan teknis, Version Name — semantik yang dapat dipahami pengguna.

Di Android kedua parameter ini independen: versionCode dapat meningkat tanpa mengubah versionName (misalnya, untuk memperbaiki kesalahan build). Di iOS, CFBundleVersion juga tidak terikat pada CFBundleShortVersionString.

Menurut data Stack Overflow Developer Survey (2024), 82% tim menggunakan increment otomatis Build Number, tetapi hanya 45% yang mengotomatiskan pembaruan Version Name — ini adalah salah satu penyebab umum kesalahan saat rilis.

Selalu tingkatkan Build Number di setiap build, bahkan jika Version Name tidak berubah — ini menjamin berfungsinya mekanisme pembaruan di toko aplikasi.

Praktik Terbaik untuk Build Number

Mulai versionCode dari 1 dan tingkatkan 1 untuk setiap build. Untuk iOS gunakan pendekatan serupa dengan CFBundleVersion. Hindari nomor gabungan jika tidak ada kebutuhan ketat — angka berurutan sederhana lebih mudah dilacak.

Hubungkan Build Number dengan nomor build sistem CI/CD — ini menyederhanakan pelacakan dari kesalahan ke commit tertentu. Git tag dengan nomor build dan versi adalah praktik terbaik untuk kontrol rilis.

Contoh Konfigurasi Build Number

Contoh kode menunjukkan cara mengkonfigurasi increment otomatis Build Number di kedua platform.

versionCode di Gradle dengan variabel CI

Di Android versionCode dapat diatur melalui variabel lingkungan CI/CD. Jika variabel tidak diatur, nilai default digunakan.

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

versionCode mendapatkan nilai dari variabel CI/CD, yang menjamin keunikan nomor untuk setiap build di pipeline.

Increment CFBundleVersion melalui agvtool

Di iOS untuk peningkatan otomatis Build Number digunakan agvtool, yang terpasang di Xcode Command Line Tools.

# Meningkatkan nomor build sebesar 1
xcrun agvtool next-version -all

# Mengatur nomor build tertentu
xcrun agvtool new-version -all "3.0.1"

Bendera -all memperbarui versi di semua target proyek, yang menjamin sinkronisasi nilai antara aplikasi utama dan ekstensi.

Fastlane untuk Otomatisasi

Fastlane — alat populer untuk otomatisasi build aplikasi mobile. Plugin increment_build_number secara otomatis meningkatkan Build Number.

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

Fastlane terintegrasi dengan sistem CI/CD apa pun dan mendukung proyek Android maupun iOS.