Building Your App in a CI Pipeline with Customized Build Servers (Private Agents)

With the expanding number of tools to help you become more productive or to improve the functionality of your app, you may have a requirement for a custom tool or specific version to be used during the build process in a Continuous Integration build. If using Visual Studio Team Services, there may be instances when the Hosted agent won’t work to build your app if you have such dependencies on tools or versions that don’t exist on the Hosted agent. Is it possible to build an app with customized build servers? Of course!

There are several benefits beyond simply the available versions of specific software to setting up your own build agents.

These include:

  1. Your server can cache dependencies such as NuGet or Maven packages.
  2. You can run incremental builds.
  3. You can have a faster machine.

Donovan Brown has an excellent article that has more detailed list on his blog.

How do I build my app in a Continuous Integration pipeline that requires custom dependencies?

In this case, you can easily install and configure a private agent that does have these dependencies installed on the machine to build your app through Visual Studio Team Services. The machine can be hosted in the cloud or on-premises as long as it can communicate back to Visual Studio Team Services. Any tool that you need installed for the build process to succeed can be installed on a machine that has a private agent on it. You just need to point the build definition to your agent pool with the private agent in it and you’re good to go.

With a private agent, there are no limits to the apps that you can build in Visual Studio Team Services. Your build definition can have any number of custom tasks and processes that you can point to the private agent. And you can use these same agents if you want to deploy to those machines as well!

How do I get started to build my app with a private agent?

If you want to host your agents on your own hardware or on VMs in the cloud, you can find detailed instructions on deploying the agent to each of our supported platforms.

We also publish container images to and of course we open source the Docker files we use to create them.

While your agent can be deployed on any cloud or on-premises machine that can access VSTS, the Azure DevTest Labs service provides some great features to help you manage both your agents and the software installed on them. Using the artifacts and formulas you can rapidly deploy a pool of identical build and release agents, there is even a built-in artifact for adding the agent to your VM. In addition to the repeatable deployment of agents, DevTest Labs has a great set of policies that can help you control your costs by automatically turning some of your agents at certain times during the day when they may not be needed. You can find a more detailed walkthrough of this process in How to Create a Monster Build Agent in Azure for Cheap! By Peter Huage.

In any of the scenarios listed above you will need to start by creating a Personal Access Token (PAT). It is important to note that this PAT is only used for the agent registration process and is not persisted to the agent machine, so you don’t have to worry about the expiration. When you create the PAT you can limit the scope to Agent Pools (read, manage).


Then, download and install the private agent onto your machine. You can add the agent to the Default agent pool or a custom agent pool that you create in Visual Studio Team Services.



Follow these steps to create a build definition.

After you’ve added in the tasks to build (and test) your app into your build definition, ensure that the Continuous Integration trigger is set in the “Triggers” tab of the definition (the branch filter may look different if you’re using TFVC).


In the “General” tab of the build definition, set the default agent queue to be “Default” or the agent pool that you configured your private agent in.


When your build definition queues automatically after code has been checked in, you’ll be able to see that your build ran on the private agent you created:


How many builds and releases can I run in parallel?

VSTS allows you to register as many build and release agents as you want with the service. However, the number of builds and release you can run concurrently is controlled by the number of pipelines you have available in your account. By default, your account includes 1 pipeline and 240 minutes of compute in the Hosted pool. This means you can run 1 concurrent build and release across all agents, hosted or private, in your account. For details on how pipelines are consumed and how you can purchase additional pipelines please see the documentation.

For further reading, see the documentation on Build and Release Agents.

We now have a Continuous Integration build pipeline that connects to a private agent that we’ve configured on our machine, a customized build server.

Visual Studio Team Services makes it easy to build any app, even if it requires custom tools or dependencies.