Build Number — ce que c’est, valeur du paramètre et incrémentation

Qu’est-ce que Build Number

Build Number est un identifiant entier unique attribué à chaque build d’une application mobile. Les magasins d’applications l’utilisent pour déterminer la nouveauté de la version — plus le nombre est élevé, plus le build est récent.

Sur Android, ce paramètre s’appelle versionCode, sur iOS — CFBundleVersion. Les deux paramètres sont obligatoires pour la publication et doivent augmenter de manière monotone à chaque nouveau build.

Selon Google Play Console Help (2025), versionCode est vérifié à chaque téléchargement d’APK : si un build avec un versionCode inférieur ou égal à celui déjà publié est téléchargé, Google Play rejette le fichier avec une erreur.

Utilisez Build Number pour le suivi interne des builds — liez le numéro au hash du commit dans votre système de contrôle de version pour identifier rapidement les releases problématiques.

Pourquoi Build Number est nécessaire

Build Number résout le problème d’identification sans ambiguïté de chaque version compilée de l’application. Sans lui, il est impossible de déterminer quel build est le plus récent si Version Name n’a pas changé.

Les magasins d’applications tels que Google Play et App Store utilisent Build Number pour résoudre les conflits lors des mises à jour. Lorsqu’un utilisateur installe une nouvelle version sur une ancienne, le système compare Build Number et propose une mise à jour uniquement si la valeur est supérieure.

Ce mécanisme est d’une importance critique pour la livraison correcte des mises à jour : sans Build Number croissant de manière monotone, les utilisateurs peuvent rester bloqués sur une version ancienne de l’application.

Formats de Build Number

Build Number peut être un simple numéro séquentiel (1, 2, 3...) ou un numéro composite encodant des informations supplémentaires. Les numéros composites incluent souvent la date de build ou le numéro de build du système CI/CD.

Pour Android, versionCode est un entier de type int, avec une valeur maximale de 2100000000. Pour iOS, CFBundleVersion est une chaîne de trois nombres séparés par des points, chacun ne dépassant pas 255.

Selon Apple Developer (2025), CFBundleVersion prend en charge jusqu’à 3 composants, mais App Store les utilise comme un seul nombre ordinal pour la comparaison des versions.

Build Number sur Android

Sur Android, Build Number est défini par le paramètre versionCode dans le fichier build.gradle. C’est un entier qui doit être unique pour chaque version de l’application publiée sur Google Play.

Le paramètre est déclaré à l’intérieur du bloc android.defaultConfig et doit augmenter à chaque nouveau release. Google Play ne permet pas de télécharger un APK avec un versionCode déjà utilisé pour une autre version de la même application.

Selon Google Play Developer API (2025), la valeur maximale de versionCode est 2100000000. Il est recommandé de commencer à 1 et d’incrémenter de 1 pour chaque nouveau build afin d’éviter d’épuiser la limite.

Utilisez un versionCode composite encodant le numéro de version : Major * 1000000 + Minor * 1000 + Patch — cela simplifie la correspondance avec la version sémantique.

Limitations de versionCode sur Android

versionCode a des limitations strictes : c’est un entier signé 32 bits, donc la valeur maximale est 2100000000. Si la limite est épuisée, l’application ne peut pas être mise à jour sur Google Play.

Pour Android App Bundle, versionCode est également spécifié dans le module de base, et chaque module de fonctionnalité peut avoir son propre versionCode. Google Play les combine en un seul système de vérification.

Cette limitation est importante à prendre en compte lors du choix d’une stratégie de versionnement — une croissance trop rapide du nombre peut entraîner des problèmes à long terme.

Build Number sur iOS

Sur iOS, Build Number est défini par la clé CFBundleVersion dans le fichier Info.plist. Contrairement à Android, ce paramètre est une chaîne, mais il doit également augmenter à chaque nouveau build.

Le format de CFBundleVersion est d’un à trois nombres séparés par des points. Chaque nombre ne peut pas dépasser 255. App Store interprète la chaîne comme une séquence de nombres pour la comparaison : 1.0.1 est considéré plus récent que 1.0.0.

Selon Apple Developer Documentation (2025), App Store Connect exige l’unicité de CFBundleVersion pour chaque build téléchargé. Si un build avec un numéro déjà utilisé est téléchargé, le système le rejette.

Gérez CFBundleVersion via agvtool ou des scripts de build Xcode pour garantir une croissance monotone du numéro à chaque build.

Intégration avec les paramètres de build Xcode

Xcode permet de gérer CFBundleVersion via les Build Settings. Le champ « Current Project Version » définit la valeur de base, et les scripts Build Phase peuvent l’incrémenter automatiquement.

Pour CI/CD, utilisez le plugin fastlane increment_build_number, qui lit la version actuelle depuis Info.plist et l’incrémente de la valeur spécifiée. Cela garantit l’unicité de chaque build.

Cette approche automatise complètement la gestion de Build Number et élimine les erreurs humaines lors de la préparation du release.

Incrémentation automatique de Build Number

L’incrémentation automatique de Build Number est une pratique standard dans les pipelines CI/CD modernes. L’incrémentation manuelle du numéro de build entraîne des erreurs et des conflits lors de la publication.

GitHub Actions, GitLab CI et Jenkins fournissent des variables intégrées avec le numéro de build. Ces variables sont utilisées dans les scripts Gradle ou Xcode pour la substitution automatique de Build Number.

Selon GitLab CI Documentation (2025), la variable CI_PIPELINE_IID garantit un numéro unique pour chaque pipeline, ce qui la rend idéale pour une utilisation comme Build Number.

Configurez l’incrémentation automatique au niveau CI/CD — cela élimine la nécessité de modifier manuellement Build Number à chaque commit dans la branche de release.

Outils d’automatisation populaires

GitHub Actions prend en charge la variable intégrée run_number, qui s’incrémente automatiquement à chaque exécution du pipeline. La valeur peut être transmise à Gradle via versionCode.

Jenkins utilise la variable BUILD_NUMBER, disponible à toutes les étapes de build. Pour les projets Xcode, Jenkins exécute agvtool avec ce numéro.

Choisissez l’outil intégré à votre stack pour minimiser la configuration supplémentaire.

Build Number et Version Name

Build Number et Version Name fonctionnent en paire : le premier est pour les machines, le second pour les personnes. Build Number garantit l’unicité technique, Version Name offre une sémantique compréhensible pour l’utilisateur.

Sur Android, ces deux paramètres sont indépendants : versionCode peut augmenter sans modifier versionName (par exemple, pour corriger une erreur de build). Sur iOS, CFBundleVersion n’est pas non plus lié à CFBundleShortVersionString.

Selon Stack Overflow Developer Survey (2024), 82 % des équipes utilisent l’incrémentation automatique de Build Number, mais seulement 45 % automatisent la mise à jour de Version Name — c’est l’une des causes fréquentes d’erreurs de release.

Incémentez toujours Build Number à chaque build, même si Version Name ne change pas — cela garantit le fonctionnement correct du mécanisme de mise à jour dans les magasins d’applications.

Bonnes pratiques pour Build Number

Commencez versionCode à 1 et incrémentez-le de 1 pour chaque build. Pour iOS, utilisez une approche similaire avec CFBundleVersion. Évitez les numéros composites sauf si strictement nécessaire — un simple numéro séquentiel est plus facile à suivre.

Lie Build Number au numéro de build du système CI/CD — cela simplifie le traçage d’une erreur jusqu’à un commit spécifique. Le tag Git avec le numéro de build et la version est une bonne pratique pour la gestion des releases.

Exemples de configuration de Build Number

Les exemples de code montrent comment configurer l’incrémentation automatique de Build Number sur les deux plateformes.

versionCode dans Gradle avec variable CI

Sur Android, versionCode peut être défini via une variable d’environnement CI/CD. Si la variable n’est pas définie, une valeur par défaut est utilisée.

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

versionCode obtient sa valeur de la variable CI/CD, ce qui garantit l’unicité du numéro pour chaque build dans le pipeline.

Incémentation de CFBundleVersion via agvtool

Sur iOS, agvtool, intégré dans Xcode Command Line Tools, est utilisé pour l’incrémentation automatique de Build Number.

# Incrémenter le numéro de build de 1
xcrun agvtool next-version -all

# Définir un numéro de build spécifique
xcrun agvtool new-version -all "3.0.1"

Le flag -all met à jour la version dans toutes les cibles du projet, garantissant la synchronisation des valeurs entre l’application principale et les extensions.

Fastlane pour l’automatisation

Fastlane est un outil populaire pour automatiser les builds d’applications mobiles. Le plugin increment_build_number incrémente automatiquement Build Number.

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

Fastlane s’intègre avec n’importe quel système CI/CD et prend en charge les projets Android et iOS.