Build Number — o que é, valor do parâmetro e incremento

O que é Build Number

Build Number é um identificador inteiro único atribuído a cada compilação de um aplicativo móvel. As lojas de aplicativos o utilizam para determinar a novidade da versão — quanto maior o número, mais recente é a compilação.

No Android este parâmetro é chamado versionCode, no iOS — CFBundleVersion. Ambos os parâmetros são obrigatórios para publicação e devem aumentar monotonicamente a cada nova compilação.

De acordo com Google Play Console Help (2025), o versionCode é verificado a cada upload de APK: se uma compilação com versionCode menor ou igual ao já publicado for enviada, o Google Play rejeita o arquivo com um erro.

Use Build Number para rastreamento interno de compilações — vincule o número ao hash do commit no seu sistema de controle de versão para identificação rápida de releases problemáticos.

Por que o Build Number é necessário

Build Number resolve o problema de identificação inequívoca de cada versão compilada do aplicativo. Sem ele, é impossível determinar qual compilação é mais recente se o Version Name não mudou.

Lojas de aplicativos como Google Play e App Store usam o Build Number para resolver conflitos durante atualizações. Quando um usuário instala uma nova versão sobre uma antiga, o sistema compara o Build Number e oferece uma atualização apenas se o valor for maior.

Este mecanismo é criticamente importante para a entrega correta de atualizações: sem um Build Number monotonicamente crescente, os usuários podem ficar presos em uma versão antiga do aplicativo.

Formatos de Build Number

Build Number pode ser um número sequencial simples (1, 2, 3...) ou composto, codificando informações adicionais. Números compostos frequentemente incluem a data de compilação ou o número de compilação do sistema CI/CD.

Para Android o versionCode é um inteiro do tipo int, com valor máximo de 2100000000. Para iOS o CFBundleVersion é uma string de três números separados por pontos, cada um não maior que 255.

De acordo com Apple Developer (2025), o CFBundleVersion suporta até 3 componentes, mas a App Store os utiliza como um único número ordinal para comparação de versões.

Build Number no Android

No Android o Build Number é definido pelo parâmetro versionCode no arquivo build.gradle. É um inteiro que deve ser único para cada versão do aplicativo publicada no Google Play.

O parâmetro é declarado dentro do bloco android.defaultConfig e deve aumentar a cada novo release. O Google Play não permite carregar um APK com versionCode que já foi usado para outra versão do mesmo aplicativo.

De acordo com Google Play Developer API (2025), o valor máximo do versionCode é 2100000000. Recomenda-se começar em 1 e incrementar em 1 para cada nova compilação para evitar esgotar o limite.

Use um versionCode composto que codifique o número da versão: Major * 1000000 + Minor * 1000 + Patch — isso simplifica a correspondência com a versão semântica.

Limitações do versionCode no Android

versionCode tem limitações estritas: é um inteiro com sinal de 32 bits, portanto o valor máximo é 2100000000. Se o limite for esgotado, o aplicativo não poderá ser atualizado no Google Play.

Para Android App Bundle o versionCode também é especificado no módulo base, e cada módulo de funcionalidade pode ter seu próprio versionCode. O Google Play os combina em um único sistema de verificação.

Esta limitação é importante considerar ao escolher uma estratégia de versionamento — um crescimento muito rápido do número pode causar problemas a longo prazo.

Build Number no iOS

No iOS o Build Number é definido pela chave CFBundleVersion no arquivo Info.plist. Ao contrário do Android, este parâmetro é uma string, mas também deve aumentar a cada nova compilação.

O formato de CFBundleVersion é de um a três números separados por pontos. Cada número não pode exceder 255. A App Store interpreta a string como uma sequência de números para comparação: 1.0.1 é considerado mais recente que 1.0.0.

De acordo com Apple Developer Documentation (2025), o App Store Connect exige unicidade do CFBundleVersion para cada compilação enviada. Se uma compilação com um número já usado for enviada, o sistema a rejeita.

Gerencie o CFBundleVersion através do agvtool ou scripts de compilação do Xcode para garantir o crescimento monotônico do número a cada compilação.

Integração com as configurações de compilação do Xcode

Xcode permite gerenciar o CFBundleVersion através das Build Settings. O campo “Current Project Version” define o valor base, e scripts de Build Phase podem incrementá-lo automaticamente.

Para CI/CD use o plugin fastlane increment_build_number, que lê a versão atual do Info.plist e a incrementa no valor especificado. Isso garante a unicidade de cada compilação.

Esta abordagem automatiza completamente o gerenciamento do Build Number e elimina erros humanos durante a preparação do release.

Incremento automático do Build Number

O incremento automático do Build Number é uma prática padrão em pipelines CI/CD modernos. O incremento manual do número de compilação leva a erros e conflitos durante a publicação.

GitHub Actions, GitLab CI e Jenkins fornecem variáveis integradas com o número de compilação. Essas variáveis são usadas em scripts Gradle ou Xcode para substituição automática do Build Number.

De acordo com GitLab CI Documentation (2025), a variável CI_PIPELINE_IID garante um número único para cada pipeline, tornando-a ideal para uso como Build Number.

Configure o incremento automático no nível CI/CD — isso elimina a necessidade de alterar manualmente o Build Number a cada commit no branch de release.

Ferramentas de automação populares

GitHub Actions suporta a variável integrada run_number, que é incrementada automaticamente a cada execução do pipeline. O valor pode ser passado para o Gradle via versionCode.

Jenkins usa a variável BUILD_NUMBER, disponível em todas as etapas de compilação. Para projetos Xcode, o Jenkins executa o agvtool com este número.

Escolha a ferramenta que está integrada ao seu stack para minimizar a configuração adicional.

Build Number e Version Name

Build Number e Version Name funcionam como um par: o primeiro é para máquinas, o segundo para pessoas. O Build Number garante a unicidade técnica, o Version Name fornece uma semântica compreensível para o usuário.

No Android estes dois parâmetros são independentes: o versionCode pode aumentar sem alterar o versionName (por exemplo, para corrigir um erro de compilação). No iOS, o CFBundleVersion também não está vinculado ao CFBundleShortVersionString.

De acordo com Stack Overflow Developer Survey (2024), 82% das equipes usam incremento automático do Build Number, mas apenas 45% automatizam a atualização do Version Name — esta é uma das causas frequentes de erros em releases.

Sempre incremente o Build Number a cada compilação, mesmo que o Version Name não mude — isso garante o funcionamento correto do mecanismo de atualização nas lojas de aplicativos.

Melhores práticas para Build Number

Comece o versionCode em 1 e incremente em 1 para cada compilação. Para iOS use uma abordagem similar com CFBundleVersion. Evite números compostos a menos que seja estritamente necessário — um número sequencial simples é mais fácil de rastrear.

Vincule o Build Number ao número de compilação do sistema CI/CD — isso simplifica o rastreamento de um erro até um commit específico. Git tag com o número de compilação e versão é uma melhor prática para gerenciamento de releases.

Exemplos de configuração do Build Number

Os exemplos de código mostram como configurar o incremento automático do Build Number em ambas as plataformas.

versionCode no Gradle com variável de CI

No Android o versionCode pode ser definido através de uma variável de ambiente CI/CD. Se a variável não estiver configurada, um valor padrão é usado.

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

versionCode obtém seu valor da variável CI/CD, o que garante a unicidade do número para cada compilação no pipeline.

Incremento do CFBundleVersion via agvtool

No iOS o agvtool, integrado ao Xcode Command Line Tools, é usado para o incremento automático do Build Number.

# Incrementar o número de compilação em 1
xcrun agvtool next-version -all

# Definir um número de compilação específico
xcrun agvtool new-version -all "3.0.1"

A flag -all atualiza a versão em todos os targets do projeto, garantindo a sincronização de valores entre o aplicativo principal e as extensões.

Fastlane para automação

Fastlane é uma ferramenta popular para automatizar a compilação de aplicativos móveis. O plugin increment_build_number incrementa automaticamente o Build Number.

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

Fastlane integra-se com qualquer sistema CI/CD e suporta tanto projetos Android quanto iOS.