Build Number — 정의, 매개변수 값 및 증가

Build Number란

Build Number는 모바일 애플리케이션의 각 빌드에 할당되는 고유한 정수 식별자입니다. 앱 스토어는 이를 사용하여 버전의 새로움을 판단합니다 — 숫자가 높을수록 빌드가 더 새로운 것입니다.

Android에서 이 매개변수는 versionCode라고 하며, iOS에서는 CFBundleVersion이라고 합니다. 두 매개변수 모두 게시에 필수이며 새로운 빌드마다 단조롭게 증가해야 합니다.

Google Play Console Help (2025)에 따르면 APK를 업로드할 때마다 versionCode가 확인됩니다. 이미 게시된 버전보다 작거나 같은 versionCode의 빌드가 업로드되면 Google Play는 오류와 함께 파일을 거부합니다.

내부 빌드 추적에 Build Number를 사용하세요 — 문제가 있는 릴리스를 빠르게 식별할 수 있도록 버전 관리 시스템의 커밋 해시에 번호를 연결하세요.

Build Number가 필요한 이유

Build Number는 빌드된 각 애플리케이션 버전의 명확한 식별 문제를 해결합니다. 이것이 없으면 Version Name이 변경되지 않은 경우 어떤 빌드가 더 새로운지 확인할 수 없습니다.

Google Play 및 App Store와 같은 앱 스토어는 업데이트 시 충돌 해결에 Build Number를 사용합니다. 사용자가 이전 버전 위에 새 버전을 설치하면 시스템이 Build Number를 비교하고 값이 더 높은 경우에만 업데이트를 제공합니다.

이 메커니즘은 올바른 업데이트 전달에 매우 중요합니다. 단조롭게 증가하는 Build Number가 없으면 사용자가 애플리케이션의 이전 버전에 머물러 있을 수 있습니다.

Build Number 형식

Build Number는 간단한 순차 번호(1, 2, 3...)이거나 추가 정보를 인코딩하는 복합 번호일 수 있습니다. 복합 번호에는 빌드 날짜나 CI/CD 시스템 빌드 번호가 포함되는 경우가 많습니다.

Android의 경우 versionCode는 int 유형의 정수이며 최대값은 2100000000입니다. iOS의 경우 CFBundleVersion은 점으로 구분된 세 개의 숫자로 구성된 문자열이며 각 숫자는 255를 초과할 수 없습니다.

Apple Developer (2025)에 따르면 CFBundleVersion은 최대 3개의 구성 요소를 지원하지만 App Store는 버전 비교를 위해 이를 단일 서수로 사용합니다.

Android의 Build Number

Android에서 Build Number는 build.gradle 파일의 versionCode 매개변수로 설정됩니다. Google Play에 게시된 각 애플리케이션 버전에 대해 고유해야 하는 정수입니다.

매개변수는 android.defaultConfig 블록 내에서 선언되며 새로운 릴리스마다 증가해야 합니다. Google Play는 동일한 애플리케이션의 다른 버전에 이미 사용된 versionCode를 가진 APK 업로드를 허용하지 않습니다.

Google Play Developer API (2025)에 따르면 versionCode의 최대값은 2100000000입니다. 제한을 소진하지 않도록 1부터 시작하여 새 빌드마다 1씩 증가시키는 것이 좋습니다.

버전 번호를 인코딩하는 복합 versionCode를 사용하세요: Major * 1000000 + Minor * 1000 + Patch — 이렇게 하면 시맨틱 버전과의 매핑이 간소화됩니다.

Android에서 versionCode 제한 사항

versionCode에는 엄격한 제한이 있습니다. 32비트 부호 있는 정수이므로 최대값은 2100000000입니다. 제한이 소진되면 Google Play에서 애플리케이션을 업데이트할 수 없습니다.

Android App Bundle의 경우 versionCode는 기본 모듈에서도 지정되며 각 기능 모듈은 자체 versionCode를 가질 수 있습니다. Google Play는 이를 단일 확인 시스템으로 결합합니다.

버전 관리 전략을 선택할 때 이 제한 사항을 고려하는 것이 중요합니다 — 숫자가 너무 빠르게 증가하면 장기적으로 문제가 발생할 수 있습니다.

iOS의 Build Number

iOS에서 Build Number는 Info.plist 파일의 CFBundleVersion 키로 설정됩니다. Android와 달리 이 매개변수는 문자열이지만 새 빌드마다 증가해야 합니다.

CFBundleVersion의 형식은 점으로 구분된 1~3개의 숫자입니다. 각 숫자는 255를 초과할 수 없습니다. App Store는 비교를 위해 문자열을 숫자 시퀀스로 해석합니다: 1.0.1이 1.0.0보다 새로운 것으로 간주됩니다.

Apple Developer Documentation (2025)에 따르면 App Store Connect는 업로드된 각 빌드에 대해 고유한 CFBundleVersion을 요구합니다. 이미 사용된 번호의 빌드가 업로드되면 시스템이 이를 거부합니다.

각 빌드에서 번호의 단조로운 증가를 보장하려면 agvtool 또는 Xcode 빌드 스크립트를 통해 CFBundleVersion을 관리하세요.

Xcode Build Settings와 통합

Xcode는 Build Settings를 통해 CFBundleVersion을 관리할 수 있습니다. “Current Project Version” 필드가 기본값을 설정하고 Build Phase 스크립트가 자동으로 증가시킬 수 있습니다.

CI/CD의 경우 Info.plist에서 현재 버전을 읽고 지정된 값만큼 증가시키는 fastlane 플러그인 increment_build_number를 사용하세요. 이는 각 빌드의 고유성을 보장합니다.

이 접근 방식은 Build Number 관리를 완전히 자동화하고 릴리스 준비 시 인적 오류를 제거합니다.

Build Number 자동 증가

Build Number의 자동 증가는 최신 CI/CD 파이프라인의 표준 관행입니다. 빌드 번호를 수동으로 증가시키면 게시 시 오류와 충돌이 발생합니다.

GitHub Actions, GitLab CI 및 Jenkins는 빌드 번호가 포함된 내장 변수를 제공합니다. 이 변수들은 Build Number 자동 대체를 위해 Gradle 또는 Xcode 스크립트에서 사용됩니다.

GitLab CI Documentation (2025)에 따르면 CI_PIPELINE_IID 변수는 각 파이프라인에 대해 고유한 번호를 보장하므로 Build Number로 사용하기에 이상적입니다.

CI/CD 수준에서 자동 증가를 구성하세요 — 이렇게 하면 릴리스 브랜치에 커밋할 때마다 Build Number를 수동으로 변경할 필요가 없습니다.

인기 있는 자동화 도구

GitHub Actions는 내장 변수 run_number를 지원하며 파이프라인이 실행될 때마다 자동으로 증가합니다. 값은 versionCode를 통해 Gradle에 전달할 수 있습니다.

Jenkins는 모든 빌드 단계에서 사용 가능한 BUILD_NUMBER 변수를 사용합니다. Xcode 프로젝트의 경우 Jenkins는 이 번호로 agvtool을 실행합니다.

추가 구성을 최소화하려면 스택에 통합된 도구를 선택하세요.

Build Number와 Version Name

Build Number와 Version Name은 한 쌍으로 작동합니다:前者는 기계용, 後者는 사람용입니다. Build Number는 기술적 고유성을 보장하고 Version Name은 사용자 친화적인 의미를 제공합니다.

Android에서 이 두 매개변수는 독립적입니다: versionCode는 versionName을 변경하지 않고 증가할 수 있습니다(예: 빌드 오류 수정). iOS에서 CFBundleVersion도 CFBundleShortVersionString에 묶여 있지 않습니다.

Stack Overflow Developer Survey (2024)에 따르면 팀의 82%가 Build Number 자동 증가를 사용하지만 Version Name 업데이트를 자동화하는 팀은 45%에 불과합니다 — 이는 릴리스 오류의 일반적인 원인 중 하나입니다.

Version Name이 변경되지 않더라도 모든 빌드에서 Build Number를 증가시키세요 — 이렇게 하면 앱 스토어에서 업데이트 메커니즘이 올바르게 작동합니다.

Build Number 모범 사례

versionCode를 1부터 시작하고 빌드마다 1씩 증가시키세요. iOS의 경우 CFBundleVersion에서 유사한 접근 방식을 사용하세요. 엄격히 필요하지 않은 한 복합 번호는 피하세요 — 간단한 순차 번호가 추적하기 더 쉽습니다.

Build Number를 CI/CD 시스템 빌드 번호에 연결하세요 — 이렇게 하면 오류에서 특정 커밋까지 추적이 간소화됩니다. 빌드 번호와 버전이 포함된 Git 태그는 릴리스 관리의 모범 사례입니다.

Build Number 설정 예제

코드 예제는 두 플랫폼 모두에서 Build Number 자동 증가를 구성하는 방법을 보여줍니다.

CI 변수를 사용한 Gradle의 versionCode

Android에서 versionCode는 CI/CD 환경 변수를 통해 설정할 수 있습니다. 변수가 설정되지 않은 경우 기본값이 사용됩니다.

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

versionCode는 CI/CD 변수에서 값을 가져와 파이프라인의 각 빌드에 대해 번호의 고유성을 보장합니다.

agvtool을 통한 CFBundleVersion 증가

iOS에서 Build Number 자동 증가를 위해 Xcode Command Line Tools에 내장된 agvtool이 사용됩니다.

# 빌드 번호 1 증가
xcrun agvtool next-version -all

# 특정 빌드 번호 설정
xcrun agvtool new-version -all "3.0.1"

플래그 -all은 프로젝트의 모든 대상에서 버전을 업데이트하여 기본 애플리케이션과 확장 간의 값 동기화를 보장합니다.

자동화를 위한 Fastlane

Fastlane은 모바일 애플리케이션 빌드를 자동화하는 인기 있는 도구입니다. increment_build_number 플러그인이 자동으로 Build Number를 증가시킵니다.

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

Fastlane은 모든 CI/CD 시스템과 통합되며 Android 및 iOS 프로젝트를 모두 지원합니다.