Last week I’ve created 2 posts on setting up VSTS and Hockeyapp in a continuous deployment scenario for both Xamarin.Android and Windows 10 UWP apps. Today we’ll discuss the 3rd platform: Apps built using Xamarin.iOS
The basics of all 3 platforms are the same but there are still quite some differences so lets look at the steps for Xamarin.iOS apps:
Context: the app we are going to deploy
We’re going to deploy the same app as yesterday in the Xamarin Android post. I’ve created a simple solution in Visual Studio containing an average Xamarin project. 1 PCL, 1 Android app, 1 iOS app and 1 Windows 10 UWP app.
To make things easier during automated build I’ve also created a new solution that only contains the projects relevant for the iOS app.
This solution only contains the PCL project and the Xamarin.iOS app project.
Setting up the build in VSTS: Prerequisites
There are some difficulties comparing the build of iOS apps to Android or Windows apps. first difficulty is that you are going to need a Mac to do the actual build steps. to do this you have 2 options. The first is to just use a Mac within your network and use that as a build agent, the other option is to use a service called MacInCloud.com which has a special plan for VSTS build agents.
Mac Build agent
Mac in cloud has a special VSTS build agent plan which only costs 30$ a month. in my experience this works really well. If you have a spare Mac somewhere to use as build agent this would also work fine but most clients I come don’t have that
Setting up a VSTS build agent on a mac isn’t that hard. There is a good guide on this on github here: https://github.com/Microsoft/vso-agent/blob/master/docs/vsts.md
make sure Xamarin Studio is installed on the mac because it’s needed for doing the actual builds. (not in the VSTS build agent guide)
To be able to build the iOS app and to do ad-hoc distribution we’re going to need to set up certificates from the apple developer portal on our mac build agent. Xamarin has a great guide on how to do this so I won’t copy all the steps in this blogpost: https://developer.xamarin.com/guides/ios/deployment,_testing,_and_metrics/app_distribution/ad-hoc-distribution/
After we’ve arranged a mac build agent and set up the app certificates we can actually start building our app.
Setting up the build in VSTS
in VSTS open your team project and go to the BUILD tab. in here we’re going to create a new build definition by clicking the green + sign.
Choose the Xamarin.iOS build template to set up the build.
In the next step select the correct repository you want to use for your app and make sure you select the Mac build agent in the drop down box.
Click Create and now our build definition is created with 2 out of the box steps. The first step is doing the actual Xamarin.iOS build. select the iOS specific solution so only the iOS related projects are build.
We’ll be removing the Xamarin test cloud step for now. if you want to know more about this let me know in a comment so I can create a new blogpost about this if people would like that.
so we only have the Xamarion.iOS step left but this will only build our app. we’re also going to need 2 extra steps which are not part of the Xamarin.iOS step:
- Nuget package restore
- Copy and Publish Artifacts.
Nuget Package restore:
I’ve you’ve read my previous posts on Android and Windows UWP you would expect we’re going to use the out of the box “restore nuget package” build step. But that is not possible for iOS. Why not? these steps are implemented using Powershell which doesn’t run on your mac agent. so we’ll have to do it manually by executing a shell script. So we’re going to create a shell script task. First we need to create the actual script. The script is quite simple. download the nuget.exe file and execute the nuget restore command
Save the .sh file in your repository so we can add it to our build step. Click the green + and select “Shell Script”
Drag the .sh script to the top of the build so the nuget restore will be executed before the actual build step. Select your .sh file in the script path and as argumenets pass in the path to your iOS solution file so the script knows what packages to restore.
Copy and Publish Artifacts
So we’ve set up the nuget restore and the build. the last step of our build is to copy and publish the build artificats so we can send these to Hockeyapp later.
Add a “Copy and Publish Build Artifacts” step to your build definition.
In the copy and publish step set the root to the correct folder and for contents we’re going to select the .ipa file. The Artifact name we’re naming “drop” of type server.
These 3 steps should together be able to do a successful build. Go to triggers to schedule your build nightly or set it to build every time someone checks in code.
Queue a build to see if everything works.
Setting up Hockeyapp
I assume you’ve already created an account at Hockeyapp otherwise just sign up at www.hockeyapp.net (It’s free for 2 apps or less) once you’ve logged in go and create your first app by pressing the New App Button
Hockeyapp will ask you to upload a build. we’re not going to do that since we’re setting up automatic deployments. choose to add the app manually
Choose iOS as the platform and fill in your release type and title of the app.
Click Save and in the overview of the app copy and save the App ID
To be able to deploy from VSTS we need to set up an API token we can use in VSTS. If you already followed the Android or Windows UWP guide you might have already taken these steps so you can skip these steps and move to the chapter of deploying the app.
Click on your user icon in the top right and select API Tokens from the menu on the left.
Create a new API token and call it VSTS. Copy this API token. we’ll need it in VSTS
Move back to VSTS and open up the marketplace (top right next to your name) and click manage extensions. browse the marketplace and install the Hockeyapp extension
After installing the extension go back to your VSTS team project and navigate to the settings window. in the settings menu go to Services and add a new service Endpoint of type “Hockeyapp”
Give the endpoint a proper name and copy in the API token you’ve generated earlier. now save the service endpoint.
Now all the plumbing with Hockeyapp is done we can actually start deploying our app to hockeyapp
Deploying your automated build to Hockeyapp
Go back to your team project in VSTS and navigate to the Release tab
Choose an Empty deployment template and press OK.
First go to the Artifact tab and select the build we’ve created earlier as supplier of the artifacts we’re going to release to hockeyapp.
Go back to Environments, name your deployment template and add a new Task
This list should now contain a Hockeyapp step since we installed that as our extension
Configure the Hockeyapp step by selecting the Hockeyapp connection from the list. (the service connection you’ve created earlier should be listed here) Enter the APP ID you copied earlier and select the .ipa file that was generated by the build.
That’s all it takes to set up the release. for the final step we’re going to set the triggers in the “Triggers” tab of the release to be deployed continuously after each build.
Press the Green + To start a manual release towards Hockeyapp. Everything should work and the release should be created in Hockeyapp.
If you have any questions let me know via twitter @geertvdc or by commenting below.
Geert van der Cruijsen