POST

Recently, Microsoft and MacinCloud announced a partnership in which they have enabled Visual Studio Team Services (VSTS) to support continuous integration (CI) builds for Xamarin.iOS and XCode projects using a Mac build agent in the cloud. This is great news as more companies are looking to move towards cloud-hosted solutions for their build and deployment pipeline.

Although MacinCloud indicates that the VSTS Agent Plan setup only takes a few minutes, the process is not fully automated and requires some manual steps in order to get your CI Builds working as expected. The initial setup is fairly quick, but your Xamarin.iOS CI builds will fail until you install a Xamarin license on the MacinCloud CI Build Server. The catch? Unlike the other MacinCloud plans, the CI Build Agent Plan does not allow you to directly interact with the Build Server. Instead, you are required to contact both MacinCloud Support and Xamarin Support to complete the process. Set your expectations that it may take anywhere from 2 – 4 days before you can start using the CI Build Agent.

Let's take a look at what is involved, from start to finish, to successfully configure a CI Build Agent for your Xamarin.iOS projects.

Step 1: Register for MacinCloud plan

In order to integrate Macincloud with Visual Studio Team Services, you need to register for a CI Build Agent plan at MacinCloud.com. The CI Build Agent cost is $29 US per month per build agent.

Step 2: Create a new VSTS Agent

Once you are registered, you must setup your build agent through the Dashboard, as shown below.

MacinCloud Dashboard

Select the Edit button to configure your MacinCloud VSTS Agent.

Step 3: Associate the MacinCloud Build Agent to your VSTS Account

In the Edit VSTS Agent dialog, enter a unique agent name and a pool name. Note that the pool name must match the name of an Agent Pool in Visual Studio Team Services.

MacinCloud Edit VSTS Agent Dialog

Enter your VSTS URL to associate this build agent with your Team Services account.

Step 4: Generate a Microsoft Access Token in VSTS for the Build Agent

Next, you will need to provide the MacinCloud Build Agent access to your VSTS account, which requires that you generate a Microsoft Access Token from your VSTS profile.

To do this, open a new browser tab, log into your VSTS account and navigate to the security tab for your account profile. Alternatively you can click the "?" button situated to the right of the Microsoft Access Token entry field in the Edit VSTS Agent dialog, which will launch the "Create a personal access token" page in your VSTS Dashboard. Provide a Description, and then select an Expiry term as well as the desired VSTS Account. Ensure All scopes is selected for Authorized Scopes then click the Create Token button.

VSTS Dashboard – Create a personal access token

Step 5: Enter the Microsoft Access Token in the MacinCloud Edit VSTS Agent dialog

Copy the generated access token to the clipboard and paste it in the MacinCloud Microsoft Access Token field in the Edit VSTS Agent dialog.

Important Note: Be sure to save a copy of the generated access token in a safe location. You will not be able to retrieve the generated access token again once you navigate away from the Security page after it has been created.

If you wish, you can add your signing certificate and provisioning profile at this time, but it's not required in the initial setup.

Click Save to create your MacinCloud CI Build Agent.

Step 6: Confirm that the MacinCloud Agent appears in the VSTS Agent Pool

Navigate to the Admin section within your VSTS Dashboard and select the Agent Pools tab. Select the Agent Pool that matches the Pool Name you entered in the MacinCloud Edit VSTS Agent dialog. If everything is configured properly, then the MacinCloud agent will appear in the Agents list, as shown below.

MacinCloud VSTS Agent associated with Default Agent Pool in VSTS

Step 7: Install Xamarin License on the Mac Server 

Last but not least, you will need to install a Xamarin license on the Mac server where your CI Build Agent is hosted. Unfortunately, MacinCloud does not provide you with interactive access to the server. This requires some back and forth correspondence with MacinCloud Support and Xamarin Support in order to finish the setup process.

Step 7a: Request System Profile Information from MacinCloud Support

First, you will need to submit a support request to MacinCloud to obtain the server information and system file that Xamarin will require in order to generate a license file for your CI Build Server.

Send an email to support@macincloud.com with the following request:

"I am setting up a CI Build Agent to configure continuous integration builds in Visual Studio Team Services for Xamarin.iOS applications. Please send me the system profile of my CI Build Agent, which I will need to forward to Xamarin support so they can generate a License file. To retrieve the system profile, perform the following steps:

– Go to: Macintosh HD -> Applications -> Utilities -> System Information.app

– Choose File > Save

– Select a location to save the file, such as the desktop, or Documents folder.

– Name and save the file.

– Please email the file to me when this is completed."

This initial email will generate a support ticket within the MacinCloud Support Portal. You will receive an email containing a link to the support request so you can view its status at any time.

Note that response time from MacinCloud Support will vary, with the expectation that it can take anywhere from a couple of hours to 1 full business day to receive a response depending on the time of day that you submit the request.

The generated system profile information file will simply be an xml file with a .spx extension.

Step 7b: Request a license from Xamarin Support

Once you receive the system profile information file from MacinCloud Support, you will need to send it to Xamarin Support. Log into your Xamarin account, go to your Dashboard and select Xamarin.iOS to locate the support email address for your subscription.

Send an email to the Xamarin Support using the specified email address, requesting a License.V2 file to be generated for your MacinCloud CI Build Agent. Be sure to attach the spx file that you received from MacinCloud to this request.

Xamarin Support will provide you with the license file and instructions on where the file should be placed on the server. The Xamarin.iOS license file must be copied to the ~/Library/MonoTouch folder on the build server.

I found the turnaround time on this request to be relatively quick.

Step 7c: Forward the license to MacinCloud Support

Forward the license file and relevant instructions to MacinCloud Support, and wait until they send a confirmation that the license has been installed on the server.

To Be Continued...

Now that you have the MacinCloud CI Build Agent properly configured, you will be able to setup continuous integration builds for your Xamarin.iOS projects! In the next post, we will walk through the necessary steps to create a Xamarin.iOS build definition in Visual Studio Team Services.