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はドット区切りの3つの数値からなる文字列で、各数値は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ではこれらの2つのパラメータは独立しています：versionCodeはversionNameを変更せずに増加できます（たとえば、ビルドエラーの修正など）。iOSでもCFBundleVersionはCFBundleShortVersionStringに結びついていません。

Stack Overflow Developer Survey（2024）によると、チームの82%がBuild Numberの自動インクリメントを使用していますが、Version Nameの更新を自動化しているのはわずか45%です — これはリリースエラーの一般的な原因の1つです。

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では、Xcode Command Line Toolsに組み込まれているagvtoolを使用してBuild Numberを自動的にインクリメントします。

# ビルド番号を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の両方のプロジェクトをサポートします。