VSTS or Visual Studio Team Services is a great DevOps tool from Microsoft and it comes as a Software-as-a-Service. While configuring build pipelines, once can choose the option to build and deploy using a hosted agent. A hosted agent is provided by Microsoft and is pre-configured with all major build tools installed like Visual Studio, Java, Ant, etc. So for many organizations, this is the simplest way to build and deploy.

However, the hosted agent might not suffice for your needs. For example, you may want to use your own testing engine or compilation engine, or you are working on a not so common programming language, etc. In such cases, you will need to setup your private build server. Private agents give you more control to install dependent software needed for your builds and deployments. In this blog post, we’ll learn how to add a build server to VSTS and also configure it for build capabilities.

Provision a new server

First, we need to configure a new server. It may have OSX, Windows, or Linux. It may also be Linux docker container. Also, it can be either on-premise and any cloud service provider. When its on-premise, it can either connect to internet using proxy or direct connection. So lots of choices over here. You can choose a server most suitable to your environment.

Provision for network configuration for server

The agent communicates with VSTS or TFS to determine which job it needs to run, and to report the logs and job status. This communication is always initiated by the agent. All the messages from the agent to VSTS or TFS happen over HTTP or HTTPS, depending on how you configure the agent. So you need to make sure that you are able to connect over port 80/443 to VSTS are allowed. If you are having a cloud virtual machine, this should already be setup for you.

Configure for authentication

To register an agent, you need to be a member of the administrator role in the agent pool. Your agent can authenticate to VSTS using Personal Access token only. It won’t work with user’s credentials, etc. For this, first login into the VSTS account https://{account_name}.visualstudio.com. Now go to the user profile from right top and then select security:

Now, we can create a personal access token:

Select a token expiry date. For the scope select Agent Pools (read, manage) and make sure all the other boxes are cleared. If its a deployment group agent, for the scope select Deployment group (read, manage) and make sure all the other boxes are cleared. Copy the token generated as VSTS will not save it for later. We’ll need this token when configuring the agent.

Download and configure the agent

Let’s first login into the private agent server by using appropriate credentials. Once its done, sign in to the VSTS account https://{account_name}.visualstudio.com. Then go to account settings -> agent pools section and create a new pool:

Provide a name for the new pool. Once its created, click download agent. This will download file on the build machine. Now go ahead and extract the files into a directory called C:\agent.

You can also choose to use below PowerShell commands for same:

PS C:\> mkdir agent ; cd agent
PS C:\agent> Add-Type -AssemblyName System.IO.Compression.FileSystem ; [System.IO.Compression.ZipFile]::ExtractToDirectory("$HOME\Downloads\vsts-agent-win7-x64-2.123.0.zip", "$PWD")

These commands may vary per OS. For example, you can use below commands on ubuntu server:

~/$ mkdir myagent && cd myagent
~/myagent$ tar zxvf ~/Downloads/vsts-agent-ubuntu.14.04-x64-2.123.0.tar.gz

Once its extracted, run the configure.cmd batch file. It will ask for certain details such as VSTS server location, PAT etc. Also, for the most part, we’ll accept defaults and click yes. Below is a quick sample from my agent:

Do make sure that account you are running it with has read-write access to C:\agent directory.

Install various build tools on server

In many cases after you deploy an agent you’ll need to install software or utilities. Generally you should install on your agents whatever software and tools you use on your dev machine. The general tools include such as Visual Studio, Java, Ant, Maven, npm, etc. Do make sure to restart vsts agent service once you are done with this.

Configure capabilities for build agent

Every agent has a set of capabilities that indicate what it can do. Capabilities are name-value pairs that are either automatically discovered by the agent software, in which case they are called system capabilities, or those that you define, in which case they are called user capabilities.

The agent software automatically determines various system capabilities such as the name of the machine, type of operating system, and versions of certain software installed on the machine. Also, environment variables defined in the machine automatically appear in the list of system capabilities.

Few build tasks may require you to advertise the capabilities so that an appropriate agent can be selected from list of pools. So, even though your server may have java installed, if you have not advertised it, your build may fail. We can configure this by navigating to the Agent pools hub and selecting the Capabilities tab for the desired agent.

Below is a quick sample:

Once all of above is done, our private agent is ready to be used. Specify the same from next time you queue the build.