Build Number — cos’è, valore del parametro e incremento

Cos’è Build Number

Build Number è un identificatore intero univoco assegnato a ogni build di un’applicazione mobile. Gli app store lo utilizzano per determinare la novità della versione — più alto è il numero, più recente è il build.

Su Android questo parametro si chiama versionCode, su iOS — CFBundleVersion. Entrambi i parametri sono obbligatori per la pubblicazione e devono aumentare monotonicamente con ogni nuovo build.

Secondo Google Play Console Help (2025), versionCode viene verificato a ogni caricamento di APK: se viene caricato un build con versionCode inferiore o uguale a quello già pubblicato, Google Play rifiuta il file con un errore.

Utilizza Build Number per il tracciamento interno dei build — collega il numero all’hash del commit nel tuo sistema di controllo versione per identificare rapidamente i release problematici.

Perché serve Build Number

Build Number risolve il problema dell’identificazione univoca di ogni versione compilata dell’applicazione. Senza di esso, è impossibile determinare quale build sia più recente se Version Name non è cambiato.

Gli app store come Google Play e App Store utilizzano Build Number per risolvere i conflitti durante gli aggiornamenti. Quando un utente installa una nuova versione sopra una vecchia, il sistema confronta Build Number e offre un aggiornamento solo se il valore è superiore.

Questo meccanismo è criticamente importante per la corretta consegna degli aggiornamenti: senza un Build Number monotonicamente crescente, gli utenti potrebbero rimanere bloccati su una versione vecchia dell’applicazione.

Formati di Build Number

Build Number può essere un semplice numero sequenziale (1, 2, 3...) o un numero composto che codifica informazioni aggiuntive. I numeri composti spesso includono la data di build o il numero di build del sistema CI/CD.

Per Android versionCode è un intero di tipo int, con valore massimo di 2100000000. Per iOS CFBundleVersion è una stringa di tre numeri separati da punti, ciascuno non superiore a 255.

Secondo Apple Developer (2025), CFBundleVersion supporta fino a 3 componenti, ma App Store li utilizza come un unico numero ordinale per il confronto delle versioni.

Build Number su Android

Su Android Build Number viene impostato dal parametro versionCode nel file build.gradle. È un intero che deve essere univoco per ogni versione dell’applicazione pubblicata su Google Play.

Il parametro viene dichiarato all’interno del blocco android.defaultConfig e deve aumentare con ogni nuovo release. Google Play non consente di caricare un APK con un versionCode già utilizzato per un’altra versione della stessa applicazione.

Secondo Google Play Developer API (2025), il valore massimo di versionCode è 2100000000. Si consiglia di iniziare da 1 e incrementare di 1 per ogni nuovo build per evitare di esaurire il limite.

Utilizza un versionCode composto che codifichi il numero di versione: Major * 1000000 + Minor * 1000 + Patch — questo semplifica la corrispondenza con la versione semantica.

Limitazioni di versionCode in Android

versionCode ha limitazioni rigorose: è un intero con segno a 32 bit, quindi il valore massimo è 2100000000. Se il limite viene esaurito, l’applicazione non può essere aggiornata su Google Play.

Per Android App Bundle versionCode viene specificato anche nel modulo base, e ogni modulo di funzionalità può avere il proprio versionCode. Google Play li combina in un unico sistema di verifica.

Questa limitazione è importante da considerare quando si sceglie una strategia di versionamento — una crescita troppo rapida del numero può causare problemi a lungo termine.

Build Number su iOS

Su iOS Build Number viene impostato dalla chiave CFBundleVersion nel file Info.plist. A differenza di Android, questo parametro è una stringa, ma deve anch’esso aumentare con ogni nuovo build.

Il formato di CFBundleVersion è da uno a tre numeri separati da punti. Ogni numero non può superare 255. App Store interpreta la stringa come una sequenza di numeri per il confronto: 1.0.1 è considerato più recente di 1.0.0.

Secondo Apple Developer Documentation (2025), App Store Connect richiede l’unicità di CFBundleVersion per ogni build caricato. Se viene caricato un build con un numero già utilizzato, il sistema lo rifiuta.

Gestisci CFBundleVersion tramite agvtool o script di build Xcode per garantire una crescita monotona del numero a ogni build.

Integrazione con le impostazioni di build di Xcode

Xcode consente di gestire CFBundleVersion tramite Build Settings. Il campo “Current Project Version” imposta il valore base, e gli script Build Phase possono incrementarlo automaticamente.

Per CI/CD utilizza il plugin fastlane increment_build_number, che legge la versione corrente da Info.plist e la incrementa del valore specificato. Questo garantisce l’unicità di ogni build.

Questo approccio automatizza completamente la gestione di Build Number ed elimina gli errori umani durante la preparazione del release.

Incremento automatico di Build Number

L’incremento automatico di Build Number è una pratica standard nelle pipeline CI/CD moderne. L’incremento manuale del numero di build porta a errori e conflitti durante la pubblicazione.

GitHub Actions, GitLab CI e Jenkins forniscono variabili integrate con il numero di build. Queste variabili vengono utilizzate negli script Gradle o Xcode per la sostituzione automatica di Build Number.

Secondo GitLab CI Documentation (2025), la variabile CI_PIPELINE_IID garantisce un numero univoco per ogni pipeline, rendendola ideale per l’uso come Build Number.

Configura l’incremento automatico a livello CI/CD — questo elimina la necessità di modificare manualmente Build Number per ogni commit nel branch di release.

Strumenti di automazione popolari

GitHub Actions supporta la variabile integrata run_number, che viene incrementata automaticamente a ogni esecuzione della pipeline. Il valore può essere passato a Gradle tramite versionCode.

Jenkins utilizza la variabile BUILD_NUMBER, disponibile in tutte le fasi di build. Per i progetti Xcode, Jenkins esegue agvtool con questo numero.

Scegli lo strumento integrato nel tuo stack per ridurre al minimo la configurazione aggiuntiva.

Build Number e Version Name

Build Number e Version Name funzionano come una coppia: il primo è per le macchine, il secondo per le persone. Build Number garantisce l’unicità tecnica, Version Name fornisce una semantica comprensibile per l’utente.

Su Android questi due parametri sono indipendenti: versionCode può aumentare senza modificare versionName (ad esempio, per correggere un errore di build). Su iOS CFBundleVersion non è legato a CFBundleShortVersionString.

Secondo Stack Overflow Developer Survey (2024), l’82% dei team utilizza l’incremento automatico di Build Number, ma solo il 45% automatizza gli aggiornamenti di Version Name — questa è una delle cause frequenti di errori di release.

Incrementa sempre Build Number a ogni build, anche se Version Name non cambia — questo garantisce il corretto funzionamento del meccanismo di aggiornamento negli app store.

Best Practice per Build Number

Inizia versionCode da 1 e incrementalo di 1 per ogni build. Per iOS utilizza un approccio simile con CFBundleVersion. Evita i numeri composti a meno che non sia strettamente necessario — un semplice numero sequenziale è più facile da tracciare.

Collega Build Number al numero di build del sistema CI/CD — questo semplifica il tracciamento da un errore a un commit specifico. Il tag Git con il numero di build e la versione è una best practice per la gestione dei release.

Esempi di configurazione di Build Number

Gli esempi di codice mostrano come configurare l’incremento automatico di Build Number su entrambe le piattaforme.

versionCode in Gradle con variabile CI

Su Android versionCode può essere impostato tramite una variabile d’ambiente CI/CD. Se la variabile non è impostata, viene utilizzato un valore predefinito.

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

versionCode riceve il suo valore dalla variabile CI/CD, garantendo l’unicità del numero per ogni build nella pipeline.

Incremento di CFBundleVersion tramite agvtool

Su iOS agvtool, integrato in Xcode Command Line Tools, viene utilizzato per l’incremento automatico di Build Number.

# Incrementa il numero di build di 1
xcrun agvtool next-version -all

# Imposta un numero di build specifico
xcrun agvtool new-version -all "3.0.1"

Il flag -all aggiorna la versione in tutti i target del progetto, garantendo la sincronizzazione dei valori tra l’applicazione principale e le estensioni.

Fastlane per l’automazione

Fastlane è uno strumento popolare per automatizzare i build di applicazioni mobili. Il plugin increment_build_number incrementa automaticamente Build Number.

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

Fastlane si integra con qualsiasi sistema CI/CD e supporta sia progetti Android che iOS.