Building a Linux Self Hosted Build Agent with WSL

In this guide, you will learn how to create a self-hosted Linux build agent on a Windows machine using Windows Subsystem for Linux (WSL). Previously, agents were built in containers or hosted on Windows; however, using WSL provides a cost-effective and straightforward solution for running Linux builds on Windows.

Overview

Our current Azure Pipelines agent pools consist of both hosted and self-hosted agents. For instance, the "DigitalStorm" agent pool includes a Windows self-hosted build agent and a Docker containerized self-hosted agent for Windows projects. When Linux builds are required, there is no need for a separate Linux machine—WSL enables a Linux environment on your Windows system.

Follow these steps to create a new self-hosted agent pool dedicated to Linux builds:

1. Open your Azure DevOps settings.
2. Navigate to Agent Pools.
3. Click on "Add pool."
4. Select the pool type as "self-hosted" (do not choose "virtual machine scale set").
5. Name the pool (for example, "Linux self-hosted builders").
6. Optionally, enable auto-provisioning of the agent pool for all projects.

Your new agent pool, named "Linux," is now ready.

Setting Up the Agent with WSL

WSL enables you to run Linux commands on a Windows machine seamlessly. To download and configure your Linux build agent, follow the steps below.

1. In your Azure DevOps agent pool, click on "New agent."
2. Select the Linux tab.
3. Choose the appropriate architecture for your system (e.g., x64 for most platforms).

Below is the sequence of commands to set up the agent in a new directory:

mkdir myagent && cd myagent
tar zxvf ~/Downloads/vsts-agent-linux-x64-3.244.1.tar.gz
./config.sh
./run.sh

Downloading and Configuring the Agent

First, download the agent tarball to your Windows Downloads folder. In WSL, the Windows drives are mounted under /mnt. Follow these steps to copy the file into your WSL environment and configure the agent:

# Copy the downloaded agent file from the Windows C drive to your WSL Downloads folder
cp /mnt/c/Users/Jeremy/Downloads/vsts-agent-linux-x64-3.244.1.tar.gz ~/Downloads/

Next, create a directory for the agent and extract the downloaded tarball:

mkdir myagent && cd myagent
tar zxvf ~/Downloads/vsts-agent-linux-x64-3.244.1.tar.gz

Then, run the configuration script:

./config.sh

During configuration, you will be prompted with the license agreement:

agent v3.244.1
(commit 67cee7d)

>> End User License Agreements:

Building sources from a TFVC repository requires accepting the Team Explorer Everywhere End User License Agreement. This step is not required for building sources from Git repositories.

A copy of the Team Explorer Everywhere license agreement can be found at:
/home/jeremy/myagent/license.html

Enter (Y/N) Accept the Team Explorer Everywhere license agreement now? (press enter for N) >

Next, you will be prompted to enter the server URL and authentication details:

• Use your Azure DevOps instance URL (e.g., https://dev.azure.com/jeremymorgankodekloud).
• Press enter for the default authentication method (Personal Access Token).
• Enter your personal access token when prompted. To create or locate a token, click your avatar in the upper right corner of Azure DevOps, then navigate to Settings > Personal Access Tokens.

During the registration process, provide the following details:

• Agent pool: Enter the name you set earlier (e.g., "Linux").
• Agent name: For example, "WSL Linux Builder."

The script will scan for available tool capabilities, register the agent with the server, and ask for a work folder. Press enter to accept the default folder _work. You should see an output similar to:

>> Register Agent:

Enter agent pool (press enter for default) > Linux
Enter agent name (press enter for DIGITALSTORM) > WSL Linux Builder
Scanning for tool capabilities.
Connecting to the server.
Successfully added the agent
Testing agent connection.
Enter work folder (press enter for _work) >
2024-09-26 16:57:30Z: Settings Saved.

Finally, start the agent:

./run.sh

The agent will output messages indicating that it is scanning for tool capabilities, connecting to the server, and listening for jobs:

Scanning for tool capabilities.
Connecting to the server.
2024-09-26 16:57:31Z: Listening for Jobs

Visual Confirmation

After configuring your agent, you can verify its status via the Azure DevOps interface:

1. Open the Azure DevOps interface to view the terminal output where the agent is running.

   

2. Check the Linux agent pool settings, where the new agent ("WSL Linux Builder") appears in the pool with its status indicated as online and idle.

   

3. Lastly, review the overall agent pool settings which now include both Windows and Linux agents.

   

Summary

This article demonstrated how to set up a Linux self-hosted build agent on a Windows machine using WSL. With just a few commands, you can transform your Windows environment into a dual-platform build server capable of executing both Windows and Linux builds. This method not only increases build flexibility but also helps reduce costs compared to provisioning separate physical or virtual Linux machines.

Thank you for reading this guide. For more details on deploying and configuring build agents, visit the Azure DevOps Documentation.