Build Number — What It Is, Parameter Value and Increment

What is Build Number

Build Number is a unique integer identifier assigned to each build of a mobile application. App stores use it to determine version novelty — the higher the number, the newer the build.

On Android this parameter is called versionCode, on iOS — CFBundleVersion. Both parameters are mandatory for publication and must monotonically increase with each new build.

According to Google Play Console Help (2025), versionCode is checked with every APK upload: if a build with a versionCode less than or equal to the already published one is uploaded, Google Play rejects the file with an error.

Use Build Number for internal build tracking — link the number to the commit hash in your version control system for quick identification of problematic releases.

Why Build Number Is Needed

Build Number solves the problem of unambiguous identification of each built application version. Without it, it is impossible to determine which build is newer if the Version Name has not changed.

App stores such as Google Play and App Store use Build Number to resolve conflicts during updates. When a user installs a new version over an old one, the system compares the Build Number and offers an update only if the value is higher.

This mechanism is critically important for correct update delivery: without a monotonically increasing Build Number, users may get stuck on an old version of the application.

Build Number Formats

Build Number can be a simple sequential number (1, 2, 3...) or a composite one encoding additional information. Composite numbers often include the build date or the CI/CD system build number.

For Android versionCode is an integer of type int, with a maximum value of 2100000000. For iOS CFBundleVersion is a string of three dot-separated numbers, each no greater than 255.

According to Apple Developer (2025), CFBundleVersion supports up to 3 components, but App Store uses them as a single ordinal number for version comparison.

Build Number on Android

On Android Build Number is set by the versionCode parameter in the build.gradle file. This is an integer that must be unique for each application version published on Google Play.

The parameter is declared inside the android.defaultConfig block and must increase with each new release. Google Play does not allow uploading an APK with a versionCode that has already been used for another version of the same application.

According to Google Play Developer API (2025), the maximum versionCode value is 2100000000. It is recommended to start at 1 and increment by 1 for each new build to avoid exhausting the limit.

Use a composite versionCode encoding the version number: Major * 1000000 + Minor * 1000 + Patch — this simplifies matching with the semantic version.

versionCode Limitations in Android

versionCode has strict limitations: it is a 32-bit signed integer, so the maximum value is 2100000000. If the limit is exhausted, the application cannot be updated on Google Play.

For Android App Bundle the versionCode is also specified in the base module, and each feature module can have its own versionCode. Google Play combines them into a single verification system.

This limitation is important to consider when choosing a versioning strategy — too rapid growth of the number can lead to problems in the long term.

Build Number on iOS

On iOS Build Number is set by the CFBundleVersion key in the Info.plist file. Unlike Android, this parameter is a string, but it must also increase with each new build.

The CFBundleVersion format is one to three dot-separated numbers. Each number cannot exceed 255. App Store interprets the string as a sequence of numbers for comparison: 1.0.1 is considered newer than 1.0.0.

According to Apple Developer Documentation (2025), App Store Connect requires uniqueness of CFBundleVersion for each uploaded build. If a build with an already used number is uploaded, the system rejects it.

Manage CFBundleVersion through agvtool or Xcode build scripts to ensure monotonic growth of the number with each build.

Integration with Xcode Build Settings

Xcode allows managing CFBundleVersion through Build Settings. The “Current Project Version” field sets the base value, and Build Phase scripts can automatically increment it.

For CI/CD use the fastlane plugin increment_build_number, which reads the current version from Info.plist and increments it by the specified value. This guarantees uniqueness of each build.

This approach fully automates Build Number management and eliminates human errors during release preparation.

Automatic Build Number Increment

Automatic increment of Build Number is a standard practice in modern CI/CD pipelines. Manual increment of the build number leads to errors and conflicts during publication.

GitHub Actions, GitLab CI and Jenkins provide built-in variables with the build number. These variables are used in Gradle or Xcode scripts for automatic Build Number substitution.

According to GitLab CI Documentation (2025), the CI_PIPELINE_IID variable guarantees a unique number for each pipeline, making it ideal for use as a Build Number.

Configure automatic increment at the CI/CD level — this eliminates the need to manually change the Build Number for each commit to the release branch.

Popular Automation Tools

GitHub Actions supports the built-in variable run_number, which automatically increments for each pipeline run. The value can be passed to Gradle via versionCode.

Jenkins uses the BUILD_NUMBER variable, which is available at all build stages. For Xcode projects, Jenkins runs agvtool with this number.

Choose the tool that is integrated into your stack to minimize additional configuration.

Build Number and Version Name

Build Number and Version Name work as a pair: the first is for machines, the second is for people. Build Number ensures technical uniqueness, Version Name provides user-friendly semantics.

On Android these two parameters are independent: versionCode can increase without changing versionName (for example, to fix a build error). On iOS CFBundleVersion is also not tied to CFBundleShortVersionString.

According to Stack Overflow Developer Survey (2024), 82% of teams use automatic Build Number increment, but only 45% automate Version Name updates — this is one of the common causes of release errors.

Always increment Build Number with each build, even if Version Name does not change — this ensures correct operation of the update mechanism in app stores.

Best Practices for Build Number

Start versionCode at 1 and increment by 1 for each build. For iOS use a similar approach with CFBundleVersion. Avoid composite numbers unless strictly necessary — a simple sequential number is easier to track.

Link Build Number with the CI/CD system build number — this simplifies tracing from an error to a specific commit. Git tag with the build number and version is a best practice for release management.

Build Number Configuration Examples

Code examples show how to configure automatic Build Number increment on both platforms.

versionCode in Gradle with CI Variable

On Android versionCode can be set via a CI/CD environment variable. If the variable is not set, a default value is used.

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

versionCode gets its value from the CI/CD variable, which guarantees uniqueness of the number for each build in the pipeline.

Incrementing CFBundleVersion via agvtool

On iOS the agvtool, built into Xcode Command Line Tools, is used for automatic Build Number increment.

# Increment build number by 1
xcrun agvtool next-version -all

# Set specific build number
xcrun agvtool new-version -all "3.0.1"

The flag -all updates the version across all project targets, ensuring synchronization of values between the main application and extensions.

Fastlane for Automation

Fastlane is a popular tool for automating mobile application builds. The increment_build_number plugin automatically increments the Build Number.

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

Fastlane integrates with any CI/CD systems and supports both Android and iOS projects.