Build Number — co to je, význam parametru a inkrement

Co je Build Number

Build Number — je jedinečný celočíselný identifikátor, který je přiřazen každému sestavení mobilní aplikace. Obchody s aplikacemi jej používají k určení novosti verze — čím větší číslo, tím novější sestavení.

V Androidu se tento parametr nazývá versionCode, v iOS — CFBundleVersion. Oba parametry jsou povinné pro publikaci a musí monotónně růst s každým novým sestavením.

Podle údajů Google Play Console Help (2025), versionCode se kontroluje při každém nahrání APK: pokud má nahrané sestavení versionCode menší nebo rovný již publikovanému, Google Play soubor s chybou odmítne.

Používejte Build Number pro interní sledování sestavení — propojte číslo s commit hash v systému pro správu verzí pro rychlou identifikaci problematického vydání.

Proč je Build Number potřeba

Build Number řeší problém jedinečné identifikace každé sestavené verze aplikace. Bez něj nelze určit, které sestavení je novější, pokud se Version Name nezměnil.

Obchody s aplikacemi, jako Google Play a App Store, používají Build Number k řešení konfliktů při aktualizaci. Pokud uživatel instaluje novou verzi přes starou, systém porovná Build Number a nabídne aktualizaci pouze při větší hodnotě.

Tento mechanismus je kritický pro správné doručování aktualizací: bez monotónně rostoucího Build Number mohou uživatelé uvíznout na staré verzi aplikace.

Formáty Build Number

Build Number může být jednoduché pořadové číslo (1, 2, 3...) nebo složené, kódující další informace. Složená čísla často obsahují datum sestavení nebo číslo sestavení systému CI/CD.

Pro Android je versionCode celé číslo typu int, maximální hodnota — 2100000000. Pro iOS je CFBundleVersion řetězec tří čísel oddělených tečkami, každé ne větší než 255.

Podle údajů Apple Developer (2025), CFBundleVersion podporuje až 3 komponenty, ale App Store je používá jako jediné pořadové číslo pro porovnávání verzí.

Build Number na Androidu

Na Androidu se Build Number nastavuje parametrem versionCode v souboru build.gradle. Je to celé číslo, které musí být jedinečné pro každou verzi aplikace publikovanou v Google Play.

Parametr se deklaruje v bloku android.defaultConfig a musí růst s každým novým vydáním. Google Play neumožňuje nahrát APK s versionCode, který již byl použit pro jinou verzi stejné aplikace.

Podle údajů Google Play Developer API (2025), maximální hodnota versionCode je 2100000000. Doporučuje se začít od 1 a zvyšovat o 1 pro každé nové sestavení, aby nedošlo k vyčerpání limitu.

Používejte složený versionCode kódující číslo verze: Major * 1000000 + Minor * 1000 + Patch — to zjednodušuje mapování na sémantickou verzi.

Omezení versionCode v Androidu

versionCode má přísná omezení: je to 32bitové celé číslo se znaménkem, takže maximální hodnota je 2100000000. Při vyčerpání limitu nebude možné aplikaci v Google Play aktualizovat.

Pro Android App Bundle se versionCode uvádí také v modulu base a každý modul feature může mít svůj vlastní versionCode. Google Play je spojuje do jednotného systému ověřování.

Toto omezení je důležité zvážit při výběru strategie verzování — příliš rychlý růst čísla může vést k dlouhodobým problémům.

Build Number na iOS

Na iOS se Build Number nastavuje klíčem CFBundleVersion v souboru Info.plist. Na rozdíl od Androidu je tento parametr řetězec, ale také musí růst s každým novým sestavením.

Formát CFBundleVersion — jedna až tři čísla oddělená tečkami. Každé číslo nesmí přesáhnout 255. App Store interpretuje řetězec jako posloupnost čísel pro porovnání: 1.0.1 je považováno za novější než 1.0.0.

Podle údajů Apple Developer Documentation (2025), App Store Connect vyžaduje jedinečnost CFBundleVersion pro každé nahrané sestavení. Pokud nahrajete sestavení s již použitým číslem, systém jej odmítne.

Spravujte CFBundleVersion pomocí agvtool nebo skriptů sestavení Xcode, abyste zaručili monotónní růst čísla při každém sestavení.

Integrace s nastavením sestavení Xcode

Xcode umožňuje spravovat CFBundleVersion prostřednictvím nastavení Build Settings. Pole „Current Project Version“ nastavuje základní hodnotu a skripty Build Phase jej mohou automaticky zvyšovat.

Pro CI/CD použijte plugin fastlane increment_build_number, který přečte aktuální verzi z Info.plist a zvýší ji o zadanou hodnotu. To zaručuje jedinečnost každého sestavení.

Tento přístup plně automatizuje správu Build Number a vylučuje lidské chyby při přípravě vydání.

Automatický inkrement Build Number

Automatický inkrement Build Number je standardní praxí v moderních CI/CD pipeline. Ruční zvyšování čísla sestavení vede k chybám a konfliktům při publikaci.

GitHub Actions, GitLab CI a Jenkins poskytují vestavěné proměnné s číslem sestavení. Tyto proměnné se používají ve skriptech Gradle nebo Xcode pro automatické dosazení Build Number.

Podle údajů GitLab CI Documentation (2025), proměnná CI_PIPELINE_IID zaručuje jedinečné číslo pro každou pipeline, což je ideální pro použití jako Build Number.

Nastavte automatický inkrement na úrovni CI/CD — to odstraní potřebu ruční změny Build Number při každém commitu do release větve.

Populární nástroje pro automatizaci

GitHub Actions podporuje vestavěnou proměnnou run_number, která se automaticky zvyšuje při každém spuštění pipeline. Hodnotu lze předat Gradle přes versionCode.

Jenkins používá proměnnou BUILD_NUMBER, která je dostupná ve všech fázích sestavení. Pro projekty Xcode Jenkins spouští agvtool s tímto číslem.

Vyberte nástroj, který je integrován do vašeho technologického stacku, abyste minimalizovali dodatečnou konfiguraci.

Build Number a Version Name

Build Number a Version Name fungují jako pár: první — pro stroje, druhý — pro lidi. Build Number zajišťuje technickou jedinečnost, Version Name — sémantiku srozumitelnou uživateli.

V Androidu jsou tyto dva parametry nezávislé: versionCode může růst beze změny versionName (například pro opravu chyby sestavení). V iOS CFBundleVersion také není vázán na CFBundleShortVersionString.

Podle údajů Stack Overflow Developer Survey (2024), 82 % týmů používá automatický inkrement Build Number, ale pouze 45 % automatizuje aktualizaci Version Name — to je jedna z častých příčin chyb při vydání.

Vždy zvyšujte Build Number při každém sestavení, i když se Version Name nemění — to zaručuje správnou funkci mechanismu aktualizací v obchodech s aplikacemi.

Nejlepší postupy pro Build Number

Začněte versionCode od 1 a zvyšujte o 1 pro každé sestavení. Pro iOS použijte analogický přístup s CFBundleVersion. Vyhněte se složeným číslům, pokud není přísná nutnost — jednoduché pořadové číslo se snáze sleduje.

Propojte Build Number s číslem sestavení systému CI/CD — to zjednodušuje sledování od chyby ke konkrétnímu commitu. Git tag s číslem sestavení a verzí je nejlepší praxí pro kontrolu vydání.

Příklady nastavení Build Number

Příklady kódu ukazují, jak nastavit automatický inkrement Build Number na obou platformách.

versionCode v Gradle s CI proměnnou

V Androidu lze versionCode nastavit přes proměnnou prostředí CI/CD. Pokud proměnná není nastavena, použije se výchozí hodnota.

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

versionCode získává hodnotu z proměnné CI/CD, což zaručuje jedinečnost čísla pro každé sestavení v pipeline.

Inkrement CFBundleVersion přes agvtool

V iOS se pro automatické zvyšování Build Number používá agvtool, který je součástí Xcode Command Line Tools.

# Zvýšení čísla buildu o 1
xcrun agvtool next-version -all

# Nastavení konkrétního čísla buildu
xcrun agvtool new-version -all "3.0.1"

Příznak -all aktualizuje verzi ve všech targetech projektu, což zaručuje synchronizaci hodnot mezi hlavní aplikací a rozšířeními.

Fastlane pro automatizaci

Fastlane — populární nástroj pro automatizaci sestavování mobilních aplikací. Plugin increment_build_number automaticky zvyšuje Build Number.

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

Fastlane se integruje s libovolným CI/CD systémem a podporuje jak Android, tak iOS projekty.