fastlane is an open source toolkit that helps you automate deployments for mobile applications in addition to helping you take care of all the tedious stuff that goes along with it. After learning that Visual Studio for Mac will be integrating with fastlane I decided to check it out and see how well it works with Xamarin.iOS.
In this guide I will show you how to build and deploy your Xamarin.iOS application to HockeyApp using fastlane. To follow this guide you will need a Mac with Visual Studio installed. As fastlane uses Ruby you might have to update your current version of Ruby, which should be preinstalled on your Mac.
We will be performing the following steps:
- Installing fastlane
- Installing Xamarin plugin
- Configuring the project
- Configuring the Fastfile
- Deploying to HockeyApp
Installing fastlane
To get you started, go to this page and follow the instructions. Since we will be working with iOS, choose iOS as platform. Select HockeyApp as beta service. You’ll notice there are additional tasks that can be implemented, e.g. integration with Slack or HipChat to alert whenever a new deployment has been made. I won’t be covering these in this post, but feel free to check these out if you want. There’s also the “Increment Build Number” task, but since fastlane is primarily meant to work with Xcode this won’t do much for us with our Xamarin application. Don’t worry though, there are other tools we can use for this that I will be showing you later in this blog post.
Once you’re done, download the files and extract them into your project directory. Your Fastfile should look like this:
Open and run the install-script in the installer directory.
You might run into the following error when running the install-script:
Couldn’t detect shell config file (bash – ~/.bash_profile)
In that case, open up a new Terminal window and execute this command to open your bash profile:
touch ~/.bash_profile; open ~/.bash_profile
In the document that opens, insert the following line and save and close the document:
export PATH="$HOME/.fastlane/bin:$PATH"
Now we’ll do a test drive just to make sure fastlane has been installed successfully. Open a Terminal and change directory to the folder where you extracted the installer-folder (not the installer-folder itself, but the parent folder). Run the following command:
fastlane beta
If everything has been set up correctly, you will be prompted by the gym task for the path of your project file. As this is only applicable if you’re developing with Xcode, abort the task and let’s install our Xamarin plugin.
Installing Xamarin plugin
As mentioned before, fastlane is primarily meant to be used with Xcode. Fortunately it supports plugins and we’ll be taking advantage of the plugin fastlane-plugin-xamarin-build which does pretty much what it sounds like: it allows us to build Xamarin projects. We will also be utilizing it to set the correct certificate and provisioning profile for our selected build configuration.
Install the plugin by running the following command:
fastlane add_plugin xamarin_build
Answer the install prompts and hopefully the plugin should install successfully. You might, however, be faced with the following error when trying to install the plugin:
An error occurred while installing json (2.1.0), and Bundler cannot continue. Make sure that `gem install json -v '2.1.0'` succeeds before bundling.
You can ignore this error. The plugin has actually been installed successfully.
Configuring the project
In order to perform the last step of deploying to HockeyApp we need to make sure that our desired build configuration for our Xamarin.iOS project exports a IPA file on build. As we are using the debug configuration for this guide we will need to configure this build. Open your iOS project’s properties from Visual Studio and navigate to “iOS IPA Options”. Make sure that “Build iTunes Packages Archive (IPA)” is checked.
Configuring the Fastfile
Now let’s update our Fastfile. We will first be verifying that the Xamarin build plugin is working properly, so update the Fastfile to look like this:
Make sure that “solution” is set to the directory of your solution file. This example is using the explicit directory, but you can also use a relative path. Also, make sure that “project” is set to the name of your Xamarin.iOS project.
Incrementing build number
More often than not you’ll want to increment your build number for each release. If you like to use an integer for your build number you can automate this into your Fastfile. By using the fastlane commands “get_info_plist_value” and “set_info_plist_value” we can easily retrieve the current build number from our Info.plist file and increment it. Insert the following code into your Fastfile and replace the paths with the ones to your project:
You can also use the “set_info_plist_value” command to set other values in the Info.plist like display name and bundle identifier.
Signing identity and Provisioning Profile
For the Xamarin build plugin to be able to build properly you need to tell it which signing certificate and provisioning profile it needs to use for the build. This can be done by using the command “xamarin_update_configuration”, which you can use to edit any property-value pair that is in your .csproj file. I will assume that you have already set up your signing identity and provisioning profile. The following code snippet sets the signing identity and provisioning profile which is registered to my app:
Deploying to HockeyApp
Our final step is to deploy the build to HockeyApp. I will assume that you have already registered your app to use HockeyApp. If not, check out this guide on how to set it up with your Xamarin.iOS project.
First we need to get the API token for the project. To do this, log in to HockeyApp and navigate to Account Settings. Navigate to API Tokens and create a new token for your selected app. To be on the safe side, select “Full Access” under Rights. Next, update your Fastfile and replace the existing “hockey” command with the following snippet and insert your API token:
Note that I am using a relative path here.
Your Fastfile should now look like this:
And there you have it! Run the “fastlane beta” command from the Terminal window to check that everything is working.
Final words
I’m using fastlane at work for a project that cannot utilize Visual Studio Team Services as our source code is located on-premise (TFS). Normally I would have used the CI/CD tools that VSTS offers, but fastlane has proven to be a great alternative. Seeing as parts of fastlane has now been integrated into Visual Studio for Mac I am sure that this is a solid framework and that it will continue to evolve to make the mobile developer’s life easier. I’m excited to see if more parts of Fastlane will be integrated into VS for Mac. Lastly I’d like to say that I have not touched Ruby before I heard about fastlane so excuse me if my Ruby code stinks.