Build Number — co to jest, znaczenie parametru i inkrementacja

Co to jest Build Number

Build Number — to unikalny całkowitoliczbowy identyfikator, który jest przypisywany każdej kompilacji aplikacji mobilnej. Sklepy z aplikacjami używają go do określania nowości wersji — im większa liczba, tym nowsza kompilacja.

W Android ten parametr nazywa się versionCode, w iOS — CFBundleVersion. Oba parametry są obowiązkowe do publikacji i muszą monotonicznie rosnąć z każdą nową kompilacją.

Według danych Google Play Console Help (2025), versionCode jest sprawdzany przy każdym przesyłaniu APK: jeśli przesyłana kompilacja ma versionCode mniejszy lub równy już opublikowanej, Google Play odrzuca plik z błędem.

Używaj Build Number do wewnętrznego śledzenia kompilacji — powiąż numer z commit hash w systemie kontroli wersji, aby szybko zidentyfikować problematyczne wydanie.

Po co jest Build Number

Build Number rozwiązuje problem jednoznacznej identyfikacji każdej zbudowanej wersji aplikacji. Bez niego niemożliwe jest określenie, która kompilacja jest nowsza, jeśli Version Name się nie zmienił.

Sklepy z aplikacjami, takie jak Google Play i App Store, używają Build Number do rozwiązywania konfliktów przy aktualizacji. Jeśli użytkownik instaluje nową wersję na starszej, system porównuje Build Number i oferuje aktualizację tylko przy większej wartości.

Ta mechanika jest krytyczna dla prawidłowego dostarczania aktualizacji: bez monotonicznie rosnącego Build Number użytkownicy mogą utknąć na starej wersji aplikacji.

Formaty Build Number

Build Number może być prostą liczbą sekwencyjną (1, 2, 3...) lub złożoną, kodującą dodatkowe informacje. Złożone numery często zawierają datę kompilacji lub numer kompilacji systemu CI/CD.

Dla Android versionCode to liczba całkowita typu int, maksymalna wartość — 2100000000. Dla iOS CFBundleVersion to ciąg trzech liczb rozdzielonych kropkami, każda nie większa niż 255.

Według danych Apple Developer (2025), CFBundleVersion obsługuje do 3 komponentów, ale App Store używa ich jako jednego numeru porządkowego do porównywania wersji.

Build Number na Android

Na Android Build Number ustawia się parametrem versionCode w pliku build.gradle. Jest to liczba całkowita, która musi być unikalna dla każdej wersji aplikacji publikowanej w Google Play.

Parametr deklaruje się w bloku android.defaultConfig i musi rosnąć z każdym nowym wydaniem. Google Play nie pozwala przesłać APK z versionCode, który został już użyty dla innej wersji tej samej aplikacji.

Według danych Google Play Developer API (2025), maksymalna wartość versionCode to 2100000000. Zaleca się zaczynać od 1 i zwiększać o 1 dla każdej nowej kompilacji, aby uniknąć wyczerpania limitu.

Używaj złożonego versionCode kodującego numer wersji: Major * 1000000 + Minor * 1000 + Patch — upraszcza to mapowanie na wersję semantyczną.

Ograniczenia versionCode w Android

versionCode ma ścisłe ograniczenia: jest to 32-bitowa liczba całkowita ze znakiem, więc maksymalna wartość to 2100000000. Po wyczerpaniu limitu aplikacja nie będzie mogła być aktualizowana w Google Play.

Dla Android App Bundle versionCode jest również określany w module base, a każdy moduł feature może mieć własny versionCode. Google Play łączy je w jeden system weryfikacji.

To ograniczenie należy uwzględnić przy wyborze strategii wersjonowania — zbyt szybki wzrost liczby może prowadzić do problemów w długiej perspektywie.

Build Number na iOS

Na iOS Build Number ustawia się kluczem CFBundleVersion w pliku Info.plist. W przeciwieństwie do Android, ten parametr jest ciągiem znaków, ale również musi rosnąć z każdą nową kompilacją.

Format CFBundleVersion — od jednej do trzech liczb rozdzielonych kropkami. Każda liczba nie może przekraczać 255. App Store interpretuje ciąg jako sekwencję liczb do porównania: 1.0.1 jest uznawany za nowszy niż 1.0.0.

Według danych Apple Developer Documentation (2025), App Store Connect wymaga unikalności CFBundleVersion dla każdej przesłanej kompilacji. Jeśli prześlesz kompilację z już użytym numerem, system ją odrzuci.

Zarządzaj CFBundleVersion przez agvtool lub skrypty kompilacji Xcode, aby zagwarantować monotoniczny wzrost numeru przy każdej kompilacji.

Integracja z ustawieniami kompilacji Xcode

Xcode pozwala zarządzać CFBundleVersion przez ustawienia Build Settings. Pole „Current Project Version“ określa wartość bazową, a skrypty Build Phase mogą automatycznie go zwiększać.

Dla CI/CD używaj wtyczki fastlane increment_build_number, która odczytuje bieżącą wersję z Info.plist i zwiększa ją o zadaną wartość. Gwarantuje to unikalność każdej kompilacji.

Takie podejście w pełni automatyzuje zarządzanie Build Number i eliminuje błędy ludzkie przy przygotowaniu wydania.

Automatyczna inkrementacja Build Number

Automatyczna inkrementacja Build Number to standardowa praktyka w nowoczesnych pipeline'ach CI/CD. Ręczne zwiększanie numeru kompilacji prowadzi do błędów i konfliktów przy publikacji.

GitHub Actions, GitLab CI i Jenkins dostarczają wbudowane zmienne z numerem kompilacji. Te zmienne są używane w skryptach Gradle lub Xcode do automatycznego podstawiania Build Number.

Według danych GitLab CI Documentation (2025), zmienna CI_PIPELINE_IID gwarantuje unikalny numer dla każdego pipeline'a, co idealnie nadaje się do użycia jako Build Number.

Skonfiguruj automatyczną inkrementację na poziomie CI/CD — to uwolni od konieczności ręcznej zmiany Build Number przy każdym commicie do gałęzi wydaniowej.

Popularne narzędzia automatyzacji

GitHub Actions obsługuje wbudowaną zmienną run_number, która automatycznie zwiększa się przy każdym uruchomieniu pipeline'a. Wartość można przekazywać do Gradle przez versionCode.

Jenkins używa zmiennej BUILD_NUMBER, która jest dostępna na wszystkich etapach kompilacji. Dla projektów Xcode Jenkins uruchamia agvtool z tym numerem.

Wybieraj narzędzie, które jest zintegrowane z twoim stosem technologicznym, aby zminimalizować dodatkową konfigurację.

Build Number a Version Name

Build Number i Version Name działają jako para: pierwszy — dla maszyn, drugi — dla ludzi. Build Number zapewnia techniczną unikalność, Version Name — zrozumiałą dla użytkownika semantykę.

W Android te dwa parametry są niezależne: versionCode może rosnąć bez zmiany versionName (na przykład w celu naprawienia błędu kompilacji). W iOS CFBundleVersion również nie jest powiązany z CFBundleShortVersionString.

Według danych Stack Overflow Developer Survey (2024), 82% zespołów używa automatycznej inkrementacji Build Number, ale tylko 45% automatyzuje aktualizację Version Name — to jedna z częstych przyczyn błędów przy wydaniu.

Zawsze zwiększaj Build Number przy każdej kompilacji, nawet jeśli Version Name się nie zmienia — gwarantuje to prawidłowe działanie mechanizmu aktualizacji w sklepach z aplikacjami.

Najlepsze praktyki dla Build Number

Rozpoczynaj versionCode od 1 i zwiększaj o 1 dla każdej kompilacji. Dla iOS używaj analogicznego podejścia z CFBundleVersion. Unikaj złożonych numerów, jeśli nie ma ścisłej potrzeby — prosty numer sekwencyjny łatwiej śledzić.

Powiąż Build Number z numerem kompilacji systemu CI/CD — upraszcza to śledzenie od błędu do konkretnego commita. Git tag z numerem kompilacji i wersją to najlepsza praktyka kontroli wydań.

Przykłady konfiguracji Build Number

Przykłady kodu pokazują, jak skonfigurować automatyczną inkrementację Build Number na obu platformach.

versionCode w Gradle ze zmienną CI

W Android versionCode można ustawić przez zmienną środowiskową CI/CD. Jeśli zmienna nie jest ustawiona, używana jest wartość domyślna.

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

versionCode otrzymuje wartość ze zmiennej CI/CD, co gwarantuje unikalność numeru dla każdej kompilacji w pipeline'ie.

Inkrementacja CFBundleVersion przez agvtool

W iOS do automatycznego zwiększania Build Number używa się agvtool, który jest wbudowany w Xcode Command Line Tools.

# Zwiększenie numeru kompilacji o 1
xcrun agvtool next-version -all

# Ustawienie konkretnego numeru kompilacji
xcrun agvtool new-version -all "3.0.1"

Flaga -all aktualizuje wersję we wszystkich targetach projektu, co gwarantuje synchronizację wartości między główną aplikacją a rozszerzeniami.

Fastlane do automatyzacji

Fastlane — popularne narzędzie do automatyzacji kompilacji aplikacji mobilnych. Wtyczka increment_build_number automatycznie zwiększa Build Number.

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

Fastlane integruje się z dowolnymi systemami CI/CD i obsługuje zarówno projekty Android, jak i iOS.