Build Incrementation Techniques for iOS Release Train

Continuous Delivery of iOS apps is essential to stay relevant in the competitive market. Companies having the infrastructure to release features to the customers as soon as it developed wins the race over the companies does manual releases from someones local Xcode. In the Continuous Delivery mode, we should be constantly uploading the iOS build to the iTunes Connect Or to the TestFlight to get the feedback from all the technical and non-technical people involved in the release. There isn’t any harm to upload the build to iTunes Connects as long as we have proper build and versioning process. In this post, we will see what are best techniques to automatically increment build numbers in the Continuous Delivery pipeline.

Release Train

Before we jump into the automatic build numbers for our iOS app, we will see how version numbers, build numbers and release trains works while submitting an iOS app to the App Store. Apple has great documentation on version number and build numbers that every iOS developer should understand. The combination of the version number and build number uniquely identify an App Store submission for an app.

  • Version Number

Version numbers of an iOS app differential the app from the previous version. We need to create separate version number for new app release. Its similar to creating release on Github using semantic versioning.  The legal version numbers would be 1.0 , 1.1.1 etc but you can not combine letter and numbers like abc.123  that would be the illegal version number. The version numbers cannot be re-used so you have to decide in advance for the major and minor releases. The new version number value MUST be greater than previously used value and it should be incrementing subsequently. The value of current version number can be found in the Info.plist file of the iOS app with key CFBundleShortVersionString  or in case of uploaded iOS app, we can check in the iTunes Connect to find out the version number. We can check current version number using Apple’s agvtool  command line tool

  • Build Number

Multiple builds can be uploaded for specific version number, however, the build number uploaded for the specific version number should be unique and in incremental order. The value of the builds number can be reused for the different version number. The value of the current build number can be found in the Info.plist  file of the iOS app with CFBundleVersion  key. We can check current version number using Apple’s agvtool  command line tool

  • Release Train

The number of builds submitted for the specific version forms Release Train for that specific version. In the release train, build number are in the incremental order and unique. The train can take multiple builds with the specific feature and we can promote any build to App Store if needed. In short, the release train is the foundation of Continuous Delivery.

Build Incrementation in Release Train

There are few strategies for incrementing the build numbers within the release trains. We will see each of them and discuss which one would be great for release trains.

  • agvtool

Apple has native command line tool to deal with version and build numbers. We can enable agvtool  and write the script to automatically increment build number in the specific release train. In order to enable agvtool, we need to make sure we have that Current Project Version and Versioning System properties are set correctly in the target build settings. Select the target build settings and search for ‘versioning’. Now, setup Current Project Version to 1 and Select the Versioning System value to “Apple Generic”. Next thing to verify is that make sure Info tab has Bundle versions and Bundle versions string, short values are set probably to 1 for the new project.

We can increment build number to next build number using the following command

When we execute this from the CI server, It updates the Info.plist files which we need to commit back to the source control once build is successfully uploaded. This is one of the drawback of this technique. We have to update source control frequently from CI server.

  • PlistBuddy

We can achieve the version bump of the build number using the PlistBuddy tool which is used for dynamically updating the plist files. We can easily write the script.

This will increment the build number by one. Again, this updates the Info.plist files which we need to commit back to the source control once build is successfully uploaded

  • Fastlane Plugin

There are some other third-party tools like Fastlane which can also do the same thing. Fastlane has actions to increment both build and version number. The increment_version_number action can be used to increment version number which has various options as well. We can bump to major or minor version as well as we can specify the version number.

The increment_build_number action can be used to update the build number values.

There is the number of options to manage the build and version numbers but these actions also use agvtool under the hood. In this case, we have to use another Fastlane action to commit version bump to commit new version back to the source control from our CI server.

Again, this approach needs integration with Github and frequent changes in the source control from Continuous Integration server.

  • Scripted Build Numbers

There is another way which doesn’t need committing back the version number from Continuous Integration server. This techniques using Scripted build based on some magic number and increment the build number accordingly. You can read more about this techniques here

This technique works very well, we just need to add another Run Script build phase which executes this script.

This will give new build number whenever we upload new build. The benefit of using this approach is we don’t have to commit the version bump back from Continuous Integration server.

Which Technique  To Use?

As of now, we have seen four different techniques to increment the build numbers in the iOS release train. Its bit tricky to choose the technique that is suitable for your iOS app. Its because it depends on the skills of the iOS developers working in the team. All the techniques will work well if scripted and managed properly. However, I would prefer the last one with the scripted build as it doesn’t involve changing source control repository from Continuous Integration server.


In the iOS Continuous Delivery pipeline, automating the version and build number saves a lot of time and we can easily form release train without any hassle using the build incrementation techniques mentioned above. Which strategy do you use for build incrementation? please let me know if I miss anything.