Build Number — qué es, valor del parámetro e incremento

Qué es Build Number

Build Number es un identificador entero único asignado a cada compilación de una aplicación móvil. Las tiendas de aplicaciones lo utilizan para determinar la novedad de la versión — cuanto mayor es el número, más reciente es la compilación.

En Android este parámetro se llama versionCode, en iOS — CFBundleVersion. Ambos parámetros son obligatorios para la publicación y deben aumentar monótonamente con cada nueva compilación.

Según Google Play Console Help (2025), versionCode se verifica con cada carga de APK: si se carga una compilación con un versionCode menor o igual al ya publicado, Google Play rechaza el archivo con un error.

Utiliza Build Number para el seguimiento interno de compilaciones — vincula el número con el hash del commit en tu sistema de control de versiones para identificar rápidamente releases problemáticos.

Por qué se necesita Build Number

Build Number resuelve el problema de la identificación inequívoca de cada versión compilada de la aplicación. Sin él, es imposible determinar qué compilación es más reciente si Version Name no ha cambiado.

Tiendas de aplicaciones como Google Play y App Store utilizan Build Number para resolver conflictos durante las actualizaciones. Cuando un usuario instala una nueva versión sobre una anterior, el sistema compara Build Number y ofrece una actualización solo si el valor es mayor.

Este mecanismo es críticamente importante para la entrega correcta de actualizaciones: sin un Build Number que aumente monótonamente, los usuarios pueden quedarse atascados en una versión antigua de la aplicación.

Formatos de Build Number

Build Number puede ser un número secuencial simple (1, 2, 3...) o compuesto, codificando información adicional. Los números compuestos a menudo incluyen la fecha de compilación o el número de compilación del sistema CI/CD.

Para Android versionCode es un entero de tipo int, con un valor máximo de 2100000000. Para iOS CFBundleVersion es una cadena de tres números separados por puntos, cada uno no mayor de 255.

Según Apple Developer (2025), CFBundleVersion admite hasta 3 componentes, pero App Store los utiliza como un único número ordinal para la comparación de versiones.

Build Number en Android

En Android Build Number se define mediante el parámetro versionCode en el archivo build.gradle. Es un entero que debe ser único para cada versión de la aplicación publicada en Google Play.

El parámetro se declara dentro del bloque android.defaultConfig y debe aumentar con cada nuevo release. Google Play no permite cargar un APK con un versionCode que ya se haya utilizado para otra versión de la misma aplicación.

Según Google Play Developer API (2025), el valor máximo de versionCode es 2100000000. Se recomienda comenzar en 1 e incrementar en 1 por cada nueva compilación para evitar agotar el límite.

Utiliza un versionCode compuesto que codifique el número de versión: Major * 1000000 + Minor * 1000 + Patch — esto simplifica la correspondencia con la versión semántica.

Limitaciones de versionCode en Android

versionCode tiene limitaciones estrictas: es un entero con signo de 32 bits, por lo que el valor máximo es 2100000000. Si se agota el límite, la aplicación no se podrá actualizar en Google Play.

Para Android App Bundle el versionCode también se especifica en el módulo base, y cada módulo de funcionalidad puede tener su propio versionCode. Google Play los combina en un único sistema de verificación.

Esta limitación es importante tenerla en cuenta al elegir una estrategia de versionado — un crecimiento demasiado rápido del número puede provocar problemas a largo plazo.

Build Number en iOS

En iOS Build Number se define mediante la clave CFBundleVersion en el archivo Info.plist. A diferencia de Android, este parámetro es una cadena, pero también debe aumentar con cada nueva compilación.

El formato de CFBundleVersion es de uno a tres números separados por puntos. Cada número no puede exceder 255. App Store interpreta la cadena como una secuencia de números para comparar: 1.0.1 se considera más reciente que 1.0.0.

Según Apple Developer Documentation (2025), App Store Connect requiere la unicidad de CFBundleVersion para cada compilación cargada. Si se carga una compilación con un número ya utilizado, el sistema la rechaza.

Gestiona CFBundleVersion mediante agvtool o scripts de compilación de Xcode para garantizar el crecimiento monótono del número con cada compilación.

Integración con la configuración de compilación de Xcode

Xcode permite gestionar CFBundleVersion a través de Build Settings. El campo “Current Project Version” establece el valor base, y los scripts de Build Phase pueden incrementarlo automáticamente.

Para CI/CD utiliza el plugin de fastlane increment_build_number, que lee la versión actual de Info.plist y la incrementa en el valor especificado. Esto garantiza la unicidad de cada compilación.

Este enfoque automatiza completamente la gestión de Build Number y elimina los errores humanos durante la preparación del release.

Incremento automático de Build Number

El incremento automático de Build Number es una práctica estándar en los pipelines CI/CD modernos. El incremento manual del número de compilación provoca errores y conflictos durante la publicación.

GitHub Actions, GitLab CI y Jenkins proporcionan variables integradas con el número de compilación. Estas variables se utilizan en scripts de Gradle o Xcode para la sustitución automática de Build Number.

Según GitLab CI Documentation (2025), la variable CI_PIPELINE_IID garantiza un número único para cada pipeline, lo que la hace ideal para usarla como Build Number.

Configura el incremento automático a nivel de CI/CD — esto elimina la necesidad de cambiar manualmente Build Number en cada commit a la rama de release.

Herramientas de automatización populares

GitHub Actions admite la variable integrada run_number, que se incrementa automáticamente en cada ejecución del pipeline. El valor se puede pasar a Gradle mediante versionCode.

Jenkins utiliza la variable BUILD_NUMBER, que está disponible en todas las etapas de compilación. Para proyectos Xcode, Jenkins ejecuta agvtool con este número.

Elige la herramienta que esté integrada en tu stack para minimizar la configuración adicional.

Build Number y Version Name

Build Number y Version Name funcionan como un par: el primero es para máquinas, el segundo para personas. Build Number garantiza la unicidad técnica, Version Name proporciona una semántica comprensible para el usuario.

En Android estos dos parámetros son independientes: versionCode puede aumentar sin cambiar versionName (por ejemplo, para corregir un error de compilación). En iOS, CFBundleVersion tampoco está vinculado a CFBundleShortVersionString.

Según Stack Overflow Developer Survey (2024), el 82% de los equipos utiliza el incremento automático de Build Number, pero solo el 45% automatiza la actualización de Version Name — esta es una de las causas frecuentes de errores en los releases.

Incrementa siempre Build Number con cada compilación, incluso si Version Name no cambia — esto garantiza el funcionamiento correcto del mecanismo de actualización en las tiendas de aplicaciones.

Mejores prácticas para Build Number

Comienza versionCode en 1 e incrementa en 1 por cada compilación. Para iOS utiliza un enfoque similar con CFBundleVersion. Evita los números compuestos a menos que sea estrictamente necesario — un número secuencial simple es más fácil de rastrear.

Vincula Build Number con el número de compilación del sistema CI/CD — esto simplifica el rastreo desde un error hasta un commit específico. Git tag con el número de compilación y la versión es una mejor práctica para la gestión de releases.

Ejemplos de configuración de Build Number

Los ejemplos de código muestran cómo configurar el incremento automático de Build Number en ambas plataformas.

versionCode en Gradle con variable de CI

En Android versionCode se puede definir mediante una variable de entorno de CI/CD. Si la variable no está configurada, se utiliza un valor por defecto.

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

versionCode obtiene su valor de la variable de CI/CD, lo que garantiza la unicidad del número para cada compilación en el pipeline.

Incremento de CFBundleVersion mediante agvtool

En iOS se utiliza agvtool, integrado en Xcode Command Line Tools, para el incremento automático de Build Number.

# Incrementar el número de compilación en 1
xcrun agvtool next-version -all

# Establecer un número de compilación específico
xcrun agvtool new-version -all "3.0.1"

El flag -all actualiza la versión en todos los targets del proyecto, garantizando la sincronización de valores entre la aplicación principal y las extensiones.

Fastlane para automatización

Fastlane es una herramienta popular para automatizar la compilación de aplicaciones móviles. El plugin increment_build_number incrementa automáticamente Build Number.

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

Fastlane se integra con cualquier sistema CI/CD y admite tanto proyectos Android como iOS.