agvtoolでXcodeプロジェクトのバージョンを管理する

agvtool（Apple Generic Versioning Tool）はXcodeプロジェクトのバージョン番号を管理するCLIツールである。 XcodeプロジェクトのCURRENT_PROJECT_VERSION（ビルド番号）とMARKETING_VERSION（バージョン番号）をコマンドラインから確認・更新できる。

前提条件

agvtoolを使用するには、Xcodeプロジェクトの設定でVERSIONING_SYSTEMをapple-genericに設定する必要がある。

XcodeのProject Settings → Build Settingsで Versioning System を Apple Generic に設定する。

この設定は.xcodeproj/project.pbxprojに以下のように記録される。

VERSIONING_SYSTEM = "apple-generic";

基本的なコマンド

ビルド番号の確認

現在のCURRENT_PROJECT_VERSION（ビルド番号）を確認する。

$ agvtool what-version

-terseオプションをつけると数値のみを出力する。

$ agvtool what-version -terse
42

バージョン番号の確認

現在のMARKETING_VERSION（バージョン番号）を確認する。

$ agvtool what-marketing-version

-terse1オプションをつけると数値のみを出力する。

$ agvtool what-marketing-version -terse1
1.2.3

ビルド番号のインクリメント

ビルド番号を1つインクリメントする。-allオプションをつけることで全ターゲットに適用する。

$ agvtool next-version -all

bumpはnext-versionのエイリアスである。

$ agvtool bump -all

ビルド番号を任意の値に変更

ビルド番号を任意の値に設定する。

$ agvtool new-version -all 100

バージョン番号を任意の値に変更

MARKETING_VERSIONを任意の値に設定する。

$ agvtool new-marketing-version 2.0.0

CI/CDでの活用例

ビルド番号をCIのビルド番号と合わせる使い方が一般的である。 GitHub ActionsでGITHUB_RUN_NUMBER環境変数を使う例は以下のとおりである。

- name: Set build number
  run: agvtool new-version -all $GITHUB_RUN_NUMBER

バージョン番号は手動でタグを打つタイミングで更新するなど、リリースフローに合わせて組み込める。

$ agvtool new-marketing-version 1.3.0
$ git add .
$ git commit -m "Bump version to 1.3.0"
$ git tag 1.3.0

参考