Build Number — какво е, значение на параметъра и инкремент

Какво е Build Number

Build Number — е уникален целочислен идентификатор, който се присвоява на всяка компилация на мобилно приложение. Магазините за приложения го използват за определяне на новостта на версията — колкото по-голямо е числото, толкова по-нова е компилацията.

В Android този параметър се нарича versionCode, в iOS — CFBundleVersion. И двата параметъра са задължителни за публикуване и трябва монотонно да нарастват с всяка нова компилация.

Според данни на Google Play Console Help (2025), versionCode се проверява при всяко качване на APK: ако качената компилация има versionCode по-малък или равен на вече публикувания, Google Play отхвърля файла с грешка.

Използвайте Build Number за вътрешно проследяване на компилации — свържете номера с commit hash в системата за контрол на версиите за бърза идентификация на проблемна версия.

Защо е необходим Build Number

Build Number решава проблема с уникалната идентификация на всяка компилирана версия на приложението. Без него е невъзможно да се определи коя компилация е по-нова, ако Version Name не се е променил.

Магазините за приложения, като Google Play и App Store, използват Build Number за разрешаване на конфликти при актуализация. Ако потребител инсталира нова версия върху стара, системата сравнява Build Number и предлага актуализация само при по-голяма стойност.

Тази механика е критична за коректното доставяне на актуализации: без монотонно нарастващ Build Number потребителите могат да останат на стара версия на приложението.

Формати на Build Number

Build Number може да бъде просто последователно число (1, 2, 3...) или съставно, кодиращо допълнителна информация. Съставните номера често включват дата на компилация или номер на компилация от CI/CD система.

За Android versionCode е цяло число от тип int, максимална стойност — 2100000000. За iOS CFBundleVersion е низ от три числа, разделени с точки, всяко не по-голямо от 255.

Според данни на Apple Developer (2025), CFBundleVersion поддържа до 3 компонента, но App Store ги използва като единен пореден номер за сравняване на версии.

Build Number на Android

На Android Build Number се задава с параметър versionCode във файла build.gradle. Това е цяло число, което трябва да бъде уникално за всяка версия на приложението, публикувана в Google Play.

Параметърът се декларира в блока android.defaultConfig и трябва да нараства с всяко ново издание. Google Play не позволява качване на APK с versionCode, който вече е използван за друга версия на същото приложение.

Според данни на Google Play Developer API (2025), максималната стойност на versionCode е 2100000000. Препоръчва се да започнете от 1 и да увеличавате с 1 за всяка нова компилация, за да избегнете изчерпване на лимита.

Използвайте съставен versionCode, кодиращ номера на версията: Major * 1000000 + Minor * 1000 + Patch — това опростява съпоставянето със семантичната версия.

Ограничения на versionCode в Android

versionCode има строги ограничения: това е 32-битово цяло число със знак, така че максималната стойност е 2100000000. При изчерпване на лимита приложението не може да бъде актуализирано в Google Play.

За Android App Bundle versionCode се посочва също в базовия модул, а всеки функционален модул може да има свой собствен versionCode. Google Play ги обединява в единна система за проверка.

Това ограничение е важно да се вземе предвид при избора на стратегия за версиониране — твърде бързият растеж на числото може да доведе до дългосрочни проблеми.

Build Number на iOS

На iOS Build Number се задава с ключ CFBundleVersion във файла Info.plist. За разлика от Android, този параметър е низ, но също трябва да нараства с всяка нова компилация.

Форматът на CFBundleVersion — от едно до три числа, разделени с точки. Всяко число не може да надвишава 255. App Store интерпретира низа като последователност от числа за сравнение: 1.0.1 се счита за по-нов от 1.0.0.

Според данни на Apple Developer Documentation (2025), App Store Connect изисква уникалност на CFBundleVersion за всяка качена компилация. Ако се качи компилация с вече използван номер, системата ще я отхвърли.

Управлявайте CFBundleVersion чрез agvtool или скриптове за компилация на Xcode, за да гарантирате монотонен растеж на номера при всяка компилация.

Интеграция с настройките за компилация на Xcode

Xcode позволява управление на CFBundleVersion чрез настройките Build Settings. Полето „Current Project Version“ задава базовата стойност, а скриптовете Build Phase могат автоматично да я увеличават.

За CI/CD използвайте плъгина fastlane increment_build_number, който чете текущата версия от Info.plist и я увеличава с дадена стойност. Това гарантира уникалността на всяка компилация.

Този подход напълно автоматизира управлението на Build Number и елиминира човешките грешки при подготовката на издание.

Автоматичен инкремент на Build Number

Автоматичен инкремент на Build Number е стандартна практика в модерните CI/CD пайплайнове. Ръчното увеличаване на номера на компилация води до грешки и конфликти при публикуване.

GitHub Actions, GitLab CI и Jenkins предоставят вградени променливи с номер на компилация. Тези променливи се използват в скриптове на Gradle или Xcode за автоматично заместване на Build Number.

Според данни на GitLab CI Documentation (2025), променливата CI_PIPELINE_IID гарантира уникален номер за всеки пайплайн, което е идеално за използване като Build Number.

Настройте автоматичен инкремент на ниво CI/CD — това ще елиминира необходимостта от ръчна промяна на Build Number при всеки commit в релизния клон.

Популярни инструменти за автоматизация

GitHub Actions поддържа вградена променлива run_number, която автоматично се увеличава при всяко изпълнение на пайплайн. Стойността може да се предаде на Gradle чрез versionCode.

Jenkins използва променлива BUILD_NUMBER, която е достъпна на всички етапи на компилация. За Xcode проекти Jenkins стартира agvtool с този номер.

Изберете инструмента, който е интегриран във вашия технологичен стек, за да минимизирате допълнителната конфигурация.

Build Number и Version Name

Build Number и Version Name работят като двойка: първият — за машини, вторият — за хора. Build Number осигурява техническа уникалност, Version Name — семантика, разбираема за потребителя.

В Android тези два параметъра са независими: versionCode може да нараства без промяна на versionName (например за коригиране на грешка при компилация). В iOS CFBundleVersion също не е обвързан с CFBundleShortVersionString.

Според данни на Stack Overflow Developer Survey (2024), 82% от екипите използват автоматичен инкремент на Build Number, но само 45% автоматизират актуализацията на Version Name — това е една от честите причини за грешки при издаване.

Винаги увеличавайте Build Number при всяка компилация, дори ако Version Name не се променя — това гарантира коректната работа на механизма за актуализация в магазините за приложения.

Най-добри практики за Build Number

Започнете versionCode от 1 и увеличавайте с 1 за всяка компилация. За iOS използвайте аналогичен подход с CFBundleVersion. Избягвайте съставни номера, ако няма строга необходимост — просто последователно число се проследява по-лесно.

Свържете Build Number с номера на компилация на CI/CD системата — това опростява проследяването от грешка до конкретен commit. Git tag с номер на компилация и версия е най-добрата практика за контрол на изданията.

Примери за настройка на Build Number

Примери за код показват как да настроите автоматичен инкремент на Build Number на двете платформи.

versionCode в Gradle с CI променлива

В Android versionCode може да се зададе чрез променлива на средата CI/CD. Ако променливата не е зададена, се използва стойност по подразбиране.

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

versionCode получава стойност от CI/CD променливата, което гарантира уникалност на номера за всяка компилация в пайплайна.

Инкремент на CFBundleVersion чрез agvtool

В iOS за автоматично увеличаване на Build Number се използва agvtool, който е вграден в Xcode Command Line Tools.

# Увеличаване на билд номера с 1
xcrun agvtool next-version -all

# Задаване на конкретен билд номер
xcrun agvtool new-version -all "3.0.1"

Флагът -all актуализира версията във всички target-ове на проекта, което гарантира синхронизация на стойностите между основното приложение и разширенията.

Fastlane за автоматизация

Fastlane — популярен инструмент за автоматизация на компилация на мобилни приложения. Плъгинът increment_build_number автоматично увеличава Build Number.

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

Fastlane се интегрира с всяка CI/CD система и поддържа както Android, така и iOS проекти.