Build Number — was es ist, Parameterwert und Inkrement

Was ist Build Number

Build Number ist eine eindeutige ganzzahlige Kennung, die jedem Build einer mobilen Anwendung zugewiesen wird. App Stores verwenden sie, um die Neuheit einer Version zu bestimmen — je höher die Zahl, desto neuer der Build.

Unter Android heißt dieser Parameter versionCode, unter iOS — CFBundleVersion. Beide Parameter sind für die Veröffentlichung zwingend erforderlich und müssen mit jedem neuen Build monoton steigen.

Laut Google Play Console Help (2025) wird versionCode bei jedem APK-Upload überprüft: Wenn ein Build mit einem versionCode hochgeladen wird, der kleiner oder gleich der bereits veröffentlichten Version ist, lehnt Google Play die Datei mit einem Fehler ab.

Verwenden Sie Build Number für die interne Build-Verfolgung — verknüpfen Sie die Nummer mit dem Commit-Hash in Ihrem Versionskontrollsystem zur schnellen Identifizierung problematischer Releases.

Warum Build Number benötigt wird

Build Number löst das Problem der eindeutigen Identifizierung jeder erstellten Anwendungsversion. Ohne sie ist es unmöglich zu bestimmen, welcher Build neuer ist, wenn Version Name sich nicht geändert hat.

App Stores wie Google Play und App Store verwenden Build Number, um Konflikte bei Updates zu lösen. Wenn ein Benutzer eine neue Version über eine alte installiert, vergleicht das System die Build Number und bietet nur bei einem höheren Wert ein Update an.

Dieser Mechanismus ist für die korrekte Zustellung von Updates entscheidend: Ohne eine monoton steigende Build Number können Benutzer auf einer alten Version der Anwendung hängen bleiben.

Build Number Formate

Build Number kann eine einfache fortlaufende Nummer (1, 2, 3...) oder eine zusammengesetzte Nummer sein, die zusätzliche Informationen codiert. Zusammengesetzte Nummern enthalten oft das Build-Datum oder die Build-Nummer des CI/CD-Systems.

Für Android ist versionCode eine Ganzzahl vom Typ int mit einem maximalen Wert von 2100000000. Für iOS ist CFBundleVersion eine Zeichenfolge aus drei durch Punkte getrennten Zahlen, jede nicht größer als 255.

Laut Apple Developer (2025) unterstützt CFBundleVersion bis zu 3 Komponenten, aber App Store verwendet sie als eine einzige Ordnungszahl zum Versionsvergleich.

Build Number unter Android

Unter Android wird Build Number durch den Parameter versionCode in der Datei build.gradle festgelegt. Es ist eine Ganzzahl, die für jede im Google Play veröffentlichte Anwendungsversion eindeutig sein muss.

Der Parameter wird innerhalb des Blocks android.defaultConfig deklariert und muss mit jedem neuen Release steigen. Google Play erlaubt nicht das Hochladen eines APK mit einem versionCode, der bereits für eine andere Version derselben Anwendung verwendet wurde.

Laut Google Play Developer API (2025) beträgt der maximale versionCode-Wert 2100000000. Es wird empfohlen, bei 1 zu beginnen und für jeden neuen Build um 1 zu erhöhen, um eine Erschöpfung des Limits zu vermeiden.

Verwenden Sie einen zusammengesetzten versionCode, der die Versionsnummer codiert: Major * 1000000 + Minor * 1000 + Patch — dies vereinfacht die Zuordnung zur semantischen Version.

versionCode-Einschränkungen unter Android

versionCode hat strenge Einschränkungen: Es ist eine 32-Bit-Ganzzahl mit Vorzeichen, daher beträgt der maximale Wert 2100000000. Wenn das Limit ausgeschöpft ist, kann die Anwendung nicht im Google Play aktualisiert werden.

Für Android App Bundle wird versionCode auch im Basismodul angegeben, und jedes Feature-Modul kann seinen eigenen versionCode haben. Google Play kombiniert sie zu einem einzigen Überprüfungssystem.

Diese Einschränkung ist bei der Wahl einer Versionierungsstrategie zu berücksichtigen — ein zu schnelles Wachstum der Zahl kann langfristig zu Problemen führen.

Build Number unter iOS

Unter iOS wird Build Number durch den Schlüssel CFBundleVersion in der Datei Info.plist festgelegt. Anders als Android ist dieser Parameter eine Zeichenfolge, muss aber ebenfalls mit jedem neuen Build steigen.

Das Format von CFBundleVersion besteht aus ein bis drei durch Punkte getrennten Zahlen. Jede Zahl darf 255 nicht überschreiten. App Store interpretiert die Zeichenfolge als Zahlenfolge zum Vergleich: 1.0.1 gilt als neuer als 1.0.0.

Laut Apple Developer Documentation (2025) verlangt App Store Connect eine eindeutige CFBundleVersion für jeden hochgeladenen Build. Wird ein Build mit einer bereits verwendeten Nummer hochgeladen, lehnt das System ihn ab.

Verwalten Sie CFBundleVersion über agvtool oder Xcode-Build-Skripte, um ein monotones Wachstum der Nummer bei jedem Build zu gewährleisten.

Integration mit Xcode Build Settings

Xcode ermöglicht die Verwaltung von CFBundleVersion über Build Settings. Das Feld „Current Project Version“ legt den Basiswert fest, und Build-Phase-Skripte können ihn automatisch erhöhen.

Für CI/CD verwenden Sie das fastlane-Plugin increment_build_number, das die aktuelle Version aus Info.plist liest und um den angegebenen Wert erhöht. Dies garantiert die Eindeutigkeit jedes Builds.

Dieser Ansatz automatisiert die Build Number-Verwaltung vollständig und schließt menschliche Fehler bei der Release-Vorbereitung aus.

Automatisches Build Number Inkrement

Das automatische Inkrement der Build Number ist eine Standardpraxis in modernen CI/CD-Pipelines. Das manuelle Erhöhen der Build-Nummer führt zu Fehlern und Konflikten bei der Veröffentlichung.

GitHub Actions, GitLab CI und Jenkins bieten integrierte Variablen mit der Build-Nummer. Diese Variablen werden in Gradle- oder Xcode-Skripten zum automatischen Ersetzen der Build Number verwendet.

Laut GitLab CI Documentation (2025) garantiert die Variable CI_PIPELINE_IID eine eindeutige Nummer für jede Pipeline, was sie ideal für die Verwendung als Build Number macht.

Konfigurieren Sie das automatische Inkrement auf CI/CD-Ebene — dies überflüssigt die manuelle Änderung der Build Number bei jedem Commit in den Release-Branch.

Beliebte Automatisierungswerkzeuge

GitHub Actions unterstützt die integrierte Variable run_number, die bei jedem Pipeline-Lauf automatisch erhöht wird. Der Wert kann über versionCode an Gradle übergeben werden.

Jenkins verwendet die Variable BUILD_NUMBER, die in allen Build-Phasen verfügbar ist. Für Xcode-Projekte führt Jenkins agvtool mit dieser Nummer aus.

Wählen Sie das Werkzeug, das in Ihren Stack integriert ist, um zusätzliche Konfiguration zu minimieren.

Build Number und Version Name

Build Number und Version Name arbeiten als Paar: Ersteres ist für Maschinen, Letzteres für Menschen. Build Number gewährleistet technische Eindeutigkeit, Version Name bietet benutzerfreundliche Semantik.

Unter Android sind diese beiden Parameter unabhängig: versionCode kann steigen, ohne dass sich versionName ändert (z. B. zur Behebung eines Build-Fehlers). Unter iOS ist CFBundleVersion ebenfalls nicht an CFBundleShortVersionString gebunden.

Laut Stack Overflow Developer Survey (2024) verwenden 82% der Teams das automatische Build Number-Inkrement, aber nur 45% automatisieren Version Name-Updates — dies ist eine der häufigen Ursachen für Release-Fehler.

Erhöhen Sie Build Number bei jedem Build, auch wenn Version Name sich nicht ändert — dies gewährleistet die korrekte Funktion des Update-Mechanismus in den App Stores.

Best Practices für Build Number

Beginnen Sie versionCode bei 1 und erhöhen Sie ihn um 1 für jeden Build. Für iOS verwenden Sie einen ähnlichen Ansatz mit CFBundleVersion. Vermeiden Sie zusammengesetzte Nummern, es sei denn, es ist unbedingt erforderlich — eine einfache fortlaufende Nummer ist leichter nachzuverfolgen.

Verknüpfen Sie Build Number mit der Build-Nummer des CI/CD-Systems — dies vereinfacht die Rückverfolgung von einem Fehler zu einem bestimmten Commit. Git-Tag mit Build-Nummer und Version ist eine Best Practice für das Release-Management.

Build Number Konfigurationsbeispiele

Codebeispiele zeigen, wie das automatische Build Number-Inkrement auf beiden Plattformen konfiguriert wird.

versionCode in Gradle mit CI-Variable

Unter Android kann versionCode über eine CI/CD-Umgebungsvariable festgelegt werden. Wenn die Variable nicht gesetzt ist, wird ein Standardwert verwendet.

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

versionCode erhält seinen Wert aus der CI/CD-Variable, was die Eindeutigkeit der Nummer für jeden Build in der Pipeline garantiert.

CFBundleVersion-Inkrement über agvtool

Unter iOS wird agvtool, das in die Xcode Command Line Tools integriert ist, für das automatische Build Number-Inkrement verwendet.

# Build-Nummer um 1 erhöhen
xcrun agvtool next-version -all

# Bestimmte Build-Nummer festlegen
xcrun agvtool new-version -all "3.0.1"

Das Flag -all aktualisiert die Version in allen Projekt-Targets und gewährleistet die Synchronisation der Werte zwischen der Hauptanwendung und Erweiterungen.

Fastlane für Automatisierung

Fastlane ist ein beliebtes Werkzeug zur Automatisierung von mobilen App-Builds. Das Plugin increment_build_number erhöht automatisch die Build Number.

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

Fastlane integriert sich mit jedem CI/CD-System und unterstützt sowohl Android- als auch iOS-Projekte.