Ken Muse

Installing VSTS Build Agents on macOS

Category:Tags:Published: October 2, 2017 Reading Time: 7 min

If you’re doing Xamarin, macOS (OS X), or iOS development work you’ve likely discovered that you need a way to automate the build of your code from Visual Studio Team Services. If you’re not familiar with setting up a private build agent macOS, the installation instructions provided by Microsoft can be a bit confusing. This post will attempt to provide you with a walkthrough of the install process. It will also guide you in configuring a working build agent on macOS. This article does not assume you are an expert with macOS or that you have any hands-on experience working in an Apple environment.

The account performing these steps should be a VSTS administrator. At a minimum, the account needs permissions to manage the agent pools in order to add the agent.

The Prerequisites

Before you begin, make sure that you have installed the development IDEs on the Mac. If you’re creating a build agent, I’m assuming you (or someone else) have most likely already installed the following two tools:

Installing Homebrew

Multiple pieces of software are required to run a build agent on macOS. To make this easier, you’ll require a tool to install some of these packages for you. The recommended package manager for macOS is Homebrew. You can use it to install a variety of supported applications using the command line.

Open the command prompt for macOS, an application called Terminal. This application can be found in Applications * Utilities (or you can press Shift+⌘+U in Finder to open that folder). Next, type the following:

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

This will download and configure the Homebrew package manager.

Homebrew Package Installation

Now we’ll install the latest versions of Git, OpenSSL, and NPM (Node Package Manager):

1brew install git
2brew install openssl
3brew install npm

There’s a known issue with the OpenSSL installation that requires a few commands to fix. These changes will ensure that the build agents have access to the 1.0 version of OpenSSL. Type the following commands to configure OpenSSL for the build agent:

1mkdir -p /usr/local/lib/
2ln -s /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib /usr/local/lib/
3ln -s /usr/local/opt/openssl/lib/libssl.1.0.0.dylib /usr/local/lib/

Finally, you will need to download two installation package file. Once downloaded, double-click to install. First, if you intend to compile Android applications, install the latest Java JDKfrom Oracle’s site. After that install the latest version of the .NET Core SDK using the PKG from the distribution site.

With all of our pre-requisites installed, we can now start the installation of the build agent.

Installing the Build Agent

It’s time to download and install the build agent. First, open the browser and go to https://github.com/Microsoft/vsts-agent/releases/. Next, you will want to find the “Latest Release” tag. Underneath that section, look for a download that begins with vsts-agent-osx. This will be the macOS binaries. Click the link to begin downloading the file. Once it is downloaded, you will need to unpack the agent. The command line instructions are on the same page as the downloads.

Important Note: The instructions start with ~/$ on the first line and ~/myagent$ on the second line. These are NOT part of the command you execute. They are just illustrating how the Terminal prompt will look inside your Home directory. In Terminal, it is normal that the ~ character is not displayed and is replaced with your user name.

An easier method is to open the Downloads folder and double-click the downloaded tar.gz file. It will immediately be unpacked and a folder will be created. Single-click the folder, then single-click the name of the folder, and rename the folder to myagent. Afterwards, press Shift+⌘+H in Finder to open your Home directory. Drag the myagent folder into the folder you just opened. The build agent is now installed.

Configuring VSTS Permissions

The agent will need to be able to connect to VSTS in order to receive the builds. To configure it, you’ll need to retrieve a PAT (Personal Access Token) from VSTS. To get this value, open VSTS (https://{your-account}.visualstudio.com/). Hover over your account image icon in the upper right corner, then choose Security.|

This will take you to the PAT page, https://{your-account}.visualstudio.com/_details/security/tokens. Press Add.

For the Description, use MacOS Build Agent or the name of the computer. This will help you understand the role of the PAT in the future. Next, specify an expiration for the PAT. For now, use 1 year. The specific permissions (or Scopes) required can vary by agent, but at a minimum you’ll typically want Agent Pools (read and manage), Project and Team (read), Packaging (read and write), and Service Endpoints (read). If you find that your build requires additional permissions, you can return to this token and change the allowed scopes at any time.

Click Create Token. The generated token will be displayed. You’ll need this for the next step.

Configuring The Agent

Now, you will return to Terminal. Type cd ~/myagent. Now, type the following:

1./config.sh

If you’re not familiar with these types of shell scripts, the leading period executes the script in the same process. Essentially, it’s the same as manually typing and executing each line in the script file. It is worth mentioning that you can launch the file from within Finder. Right-click config.sh and choose Open With, then choose Other…. Change Enable to *All Applications. *Click the Utilities folder and select Terminal. Press Open. The script file execute in Terminal.

This command will step you through a configuration wizard. You will need to know two things: the URL to your VSTS instance and the PAT from the previous section. You will be prompted with a series of questions. Enter the account URL and PAT value when prompted; for everything else, just press Enter.

1Enter server URL > https://{your-account}.visualstudio.com
2Enter authentication type (press enter for PAT) >
3Enter personal access token > **********************************************
4Enter agent pool (press enter for default) >
5Enter agent name (press enter for my-mac) >
6Scanning for tool capabilities.
7Connecting to the server.

The agent is configured. You can start it interactively using ./run. The agent will connect to VSTS and wait for a build request. Of course, most people do not want to manually launch the agent. Instead, they want it to launch and run automatically in the background. In macOS, code which runs in the background of the logged in user’s account is called a launch agent.

Creating A Launch Agent

For many macOS users, running as a launch agent is ideal because they sign into the Mac environment to allow for interactive testing and debugging using their own account. They may also have the Mac running on the same network as a developer PC so that Visual Studio can connect and take advantage of the Xamarin agent for rendering the UIs and testing using the simulator. Thankfully, it’s very easy to setup the build agent as a launch agent. You just need to run two more commands in Terminal. Type:

1./svc.sh install

This will configure the launch agent, creating the files required for automatically launching the service. Now, you need to start the service:

1./svc.sh start

This will launch the service and allow it to start taking requests. If you open the VSTS Agent Pools(https://{your-account}.visualstudio.com/_admin/_AgentPool), you will see the service is configured and running.

Using Your Agent

To use the agent as part of an automated VSTS pipeline, you will want to ensure that the Build definition uses the Default pool. The Default pool typically contains all of the private build agents.

If you have multiple private build agents running in the Default pool, then you will also need to ensure that builds which require the Mac will go to the proper build agent. To do this, you will use a feature of the agents called Capabilities*.* Capabilities describe the features available on a given build agent. This guarantees that a build is only processed on an agent which has all of the prerequisites required to compile the application.

To specify that your build requires a specific capability, you need to configure an appropriate Demand in the Options tab of your build process. Demand the capability name Agent.OS equals Darwin to ensure the build will be executed in a macOS environment. Darwin is an open source Unix released by Apple; it is the basis for the kernel and drivers that make up macOS. As a result, checking for the OS name ‘Darwin’ ensures that we are running on a Mac build agent.

That’s it. You now have a build agent running on macOS and can configure a build to to require a private macOS build agent. Congratulations!