> This article is part of blog series VSTS, Xamarin and Continuous Integration. Why does it matter?

When we set up build definitions in Visual Studio Team Services, we require a machine or a host (called Build agent) which will perform all the steps we define in build definitions. For Xamarin iOS projects it is recommended or rather required to have a machine that is running Mac OS or macOS as per new nomenclature.

Why? In order to build iOS apps, Xamarin requires Mac Agent to access iOS SDK, XCode compiler, interface builder, keychain certificates and provisioning profile configurations since Apple has not made those available for other platforms (Sad but we got to accept it).

There are two ways of getting your own build agent. First is to use third party provider like MacInCloud.com which cost you several dollars a month, other alternative is to setup your own build agent. Benefit of having your own build agent is you have total control over it and you can reuse it for other purposes while keeping build agent as a service in background.

This article will walk you through steps required for setting up your own build agent. While there are other tutorials (even on VSTS github) that walk you through the steps for setting up your own agent, there are several missing points in almost all the tutorials. I will try to cover them up.

Prerequisites

First things first, you will need a machine running Mac OSX (or later). Install following packages / applications -

1. XCode
2. Xamarin with iOS
3. Homebrew (I will explain why we need this)
4. NPM (For deploying packages in Hockey App)
5. OpenSSL

Installing XCode

Install XCode from Mac app store (https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12). If you want to stay on bleeding edge, dead over to https://developer.apple.com/download/ and download latest package and install it. I always recommend stable builds from Mac app store though.

Installing and Configuring Xamarin

Follow this article by Xamarin that demonstrates the setup and configuration of Xamarin on Mac OS - https://developer.xamarin.com/guides/ios/getting_started/installation/mac/

Installing Homebrew

What is Homebrew?

Homebrew is a package manager for Mac. It makes users' life easy with beautiful commands like brew install node

There are several packages that are required to be installed on build agent to be able to perform build steps hassle free. I could have shown you standard ways of installing these packages however if you are new user to Mac / Linux ecosystem you will find them quite difficult. Homebrew makes it easy like anything.

• Copy this script -

  /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  view raw installhomebrew.sh hosted with ❤ by GitHub

• Open Terminal and paste the script.

• Hit "Return" when prompted and enter your user / system password (the script requires password for sudo access)

• Wait for the script to do the magic, if all goes well. You will have Homebrew successfully installed on your machine.

• Run brew list to confirm if homebrew is installed without any issue.

Install OpenSSL

VSTS agent requires proper OpenSSL version before it can be successfully installed on your machine. Following steps will install / update OpenSSL version on your machine -

• Copy and paste these commands in Terminal -

  	brew install openssl
  	brew link openssl --force

  view raw wrapcode-install-openssl.sh hosted with ❤ by GitHub

• brew install openssl will fetch latest OpenSSL package from internet and install it under usr/local (does not require sudo permission)

• brew link openssl --force creates symlinks to installations you performed manually in Cellar. This allows you to have the flexibility to install things on your own but still have those participate as dependencies in homebrew formulas.

Install NPM

• Copy and paste following commands in terminal -

  brew install node

  view raw wrapcode-install-npm.sh hosted with ❤ by GitHub

• Sit down and relax, brew a coffee maybe? To make sure you have Node and NPM installed, run two simple commands to see what version of each is installed: to see if Node is installed, type node -v and npm -v to see if NPM is installed in Terminal. Both the commands should print a version number of respective packages

Installing VSTS agent

1. Configure Account and Roles

1. Create a PAT token - Follow this article (https://www.visualstudio.com/en-us/docs/setup-admin/team-services/use-personal-access-tokens-to-authenticate) from Visual Studio to acquire PAT token. Copy it somewhere, you will need it in later installation phase.

2. Give user administrator rights

The user we are going to use while setting up VSTS agent requires "administrative rights" to register a new tenant.

1. Go to https://{tenantname}.visualstudio.com/admin
2. Go to Agent pools, select pool from left panel and then select roles tab and add user you want to give "Administrator" rights to -

> The role is only needed to register the agent. A token is downloaded to listen to the queue. When a build is run, it will generate an OAuth token for the scoped identity selected on the general tab of the build definition. That token is short lived and will be used to access resource in VSTS. The account used to register the agent has no bearing on the build run time credentials

3. Download agent from Github

Download latest package of VSTS agent from VSTS Agent Releases | Github

4. Create a separate workspace for agent

1. Open Terminal app and type following commands (you can customize folder names / paths as per your wish)

   	~/$ mkdir vstsagent && cd vstsagent
   	~/vstsagent tar xzf ~/Downloads/vsts-agent-osx.10.11-x64-2.102.1.tar.gz

   view raw install-vsts-agent.txt hosted with ❤ by GitHub

Remember, if you have different **Downloads **folder, you need to change it in above command.

5. Install and Configure the agent

Run this command in terminal -

The script expects some inputs from user like

1. Enter server URL - Your visualstudio.com tenant
2. Enter authentication type (press enter for PAT) - Simply press Return or type PAT and hit return as we are using PAT as authentication method
3. Enter personal access token - Paste PAT acquired in this step.
4. Enter agent pool - Press enter / return for default or you can provide custom pool name if you have created.
5. Enter agent name - This should pick up default machine name if pressed enter / return without entering anything. If you want to enter custom name, you can enter custom name at this point.
6. Enter work folder - Default folder for _work. You can enter another name if you want to though.
7. Enter run agent as service? (Y / N) - Default is N. However we would want this to be run as service so chose Y. If you have pressed enter without reading, don't worry. I will show you another way of starting agent as a daemon service.

6. Managing agent

Start agent interactively

Run this command

Start agent as a service / daemon

Install VSTS LaunchAgent service

Open terminal and copy following command to start VSTS as a service.

Start VSTS agent

Stop VSTS agent

Check agent status

Once you successfully configure agent, you should see a folder structure similar to this -

]

Steps to confirm whether the build agent has successfully been configured with visualstudio.com tenant -

1. Go to your tenant admin - https://{tenantname}.visualstudio.com/admin
2. Go to Agent Pools
3. Select Pool you selected while configuring agent (Default is Default)
4. You should see the build agent for selected pool with capabilities - ]\

You can now configure build and release definitions for Xamarin iOS or Mac applications on this build agent.

Questions, feedback or comments are welcome through Comments :-)

Thanks, RP