Installing a self hosted Windows build agent

May 28, 2020

Installing a self hosted Windows build agent

In the last 2 months the .NET team has been migrating our codebase for our clients from Gitlab and TeamCity to Azure Devops. I wrote this blog piece for future documentation of installing extra build agents or for the people who would like a private build agent. Most of the information can already be found on the internet on multiple sources but this blog piece tries to aggregate all these sources and above that adding my findings installing a build agent for the .NET team.

Creating Personal Access Token

For making the connection between the build agent and the Azure Devops environment you need to authorize it by creating a personal access token. To do this, navigate to Azure Devops and click on the user icon with cogwheel, followed by Personal Access Token. In the menu that opens create a new token with the properties set for Agent Pools to “Read & Manage”, make sure the other entries in the list are not checked in any capacity. An access token will be generated. Note the access token down because this is needed further in the process of creating the build agent.

create a new personal access token

Setup Virtual Machine

By default, Microsoft offers a default build agent called a Microsoft Hosted Agent, you do not have to pay extra for this. The downside is that that you only have a specific amount of build minutes each month (1800 minutes). Also, each build is totally independent of each other this means that no NuGet cache can be build, having a NuGet cache shaves of 1 minute of build time. Another positive of having a self-hosted agent is that you can have a dedicated IP that can then be handed over to clients for whitelisting.

For demo purposes I setup a virtual machine which I am going to use to install the build agent. The settings I used for this demo are as follows:

build agent settings
The above most closely resembles the speed of the Microsoft hosted agent and is also made for short bursts of activity instead of a virtual machine that is actively working throughout the day.

If you want a quick way to install a build agent, I also recommend choosing the image with Visual Studio 2019 preinstalled, else you have to install “Visual Studio build tools (2015)” separately. To this within the azure portal navigate to creating a resource and type in: “Visual Studio 2019 Latest” and click the result.

During setup make also sure to open the port for RDP so you can immediately access the virtual machine after it done being setup.

Create an agent within Azure Devops

In the next step we are registering the virtual machine with Azure Devops. By doing this, Azure Devops will send over code to build and send it back as a package. Start by logging into Azure Devops and click on organization settings in the bottom right, followed by agent pool. In the next screen you can make another agent pool or make us of the default pool. If you choose to make your own pool, select the “self-hosted” option in the drop-down menu.

A pool is a collection of agents, later in the build steps you can enter the desired pool. When a project gets triggered to be build it will go into the pool and take the first agent that is available in the pool.

After creating a pool, open the pool by clicking on it and click on “new agent” in the top right corner of the page. Download the package that is provided and make note of the first PowerShell script.

Installing agent on the virtual machine

Open the RDP executable that you downloaded previously and log into the virtual machine. Transfer the downloadable agent package to the virtual machine and unpack it in a folder. The unpacked package has two folders and two command (.cmd) files. Open the config.cmd in a command line prompt. When the config.cmd has been opened it will go through the installation process, at a certain point it will ask for the server URL of Devops which is:

https://dev.azure.com/{your-organization}

When it chooses for authentication type select PAT and put in the personal access token you made earlier. In the last step it will be asked if the agent needs to run as a service or interactively, select service so it will run in the background as a service.

If everything is done correctly, navigate back to Azure Devops and go to the pool that is created earlier, and the agent should be added.

To call on the agent within a build definition, at the top of the .YAML file insert the following piece of code above the variable definitions without brackets:

pool: [name-of-the-pool]

Wesley Rensenbrink

Wesley Rensenbrink

.NET Developer