How to setup a Private Agent in Visual Studio Team Services

In the last post about VSTS (Visual Studio Team Services) we setup the foundations for a project.

In this we install a private agent to build and deploy our project.

VSTS provides hosted agents to build and deploy. When we use a hosted agent, Microsoft takes care of the maintenance and upgrades. So for many teams this is the simplest way. 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.
If the hosted agents do not suit our needs we can setup our dedicated agent and that’s the topic of this post.

1. Setup the agent machine

The first step we need to do is to setup the machine where we’ll install the VS agent. With this I mean we need to install all the SDK, libraries, packages, etc that our project needs to build. After that we install the VS agent.

2. Download the VS agent

First we need to go in the Agent Pools section of VSTS from browser in the machine where we want to install the agent.

From here we click the Download Agent button.

We choose our operating system and then click download.

When the download completes we can follow the instructions provided by MS in the same page or we can extract the content of the zip folder with the Windows user interface. We unzip the folder in a dedicated directory, for example C:\vs-agent.

3. Install the agent

Now we run the config bat file.

The installation procedure asks us our server URL of VSTS.

Then it asks the authentication type to communicate with VSTS. We’ll use a Personal Access Token (PAT). So we simply press enter because it is the default value.

Now we need to go back to VSTS to generate a PAT.

From our profile icon in the top-right corner we access the Security section.

Where we create a new token. We choose a name, the validity time and the reference account. We specify the authorized scopes, too. In this example for semplicity we set “All Scopes” but we prefer to give the minimum set of functionalities for our production/business purposes.

When we click on Create Token, VSTS will show us our token that we must save in a safe place right now because we won’t be able to see it anymore in the future.

With the token in our clipboard we ho back to the installation of the agent and right-click with the command prompt to paste the token and press Enter.

The agent tries to connect and if the test is OK we need to specify the Agent Pool name where the agent will be inserted. If we want to create a new Agent Pool we go back to VSTS in the Agent Pool section and create a new Pool.

Now we can write the name in the prompt. (MadLab)

And now we give our agent a name (VsAgent1).

For the other options we’ll always choose the default option by pressing Enter when needed. At the end the process will like something like the following picture.

If we go back to VSTS we can see that agent has been recognized with all its capabilities.

TL; DR

The installation of a private agent is quick and simple. This enable us to avoid the limitations of the hosted agent if our project has particular needs of SDKs, libraries and so on.

For this example I installed the agent into an Azure VM with Windows Server 2016.