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 також вказується в модулі base, а для кожного модуля feature може бути свій 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 Build Settings

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 при кожному коміті в релізну гілку.

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

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 не змінюється — це гарантує коректну роботу механізму оновлень у магазинах додатків.

Best Practices для Build Number

Починайте versionCode з 1 і збільшуйте на 1 для кожної збірки. Для iOS використовуйте аналогічний підхід з CFBundleVersion. Уникайте складених номерів, якщо немає суворої необхідності — просте послідовне число легше відстежувати.

Пов'язуйте Build Number з номером збірки CI/CD системи — це спрощує трасування від помилки до конкретного коміту. 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 оновлює версію у всіх таргетах проекту, що гарантує синхронізацію значень між основним додатком і розширеннями.

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 проекти.