Exploring Self Hosted Build Agents

Self-hosted build agents are machines you manage to run builds and deployments for Azure DevOps projects. Unlike Microsoft-hosted agents, self-hosted agents provide complete control over the build environment. This enables you to customize software, security settings, and install any required tools on your local machine rather than in the cloud. This approach not only enhances performance and customization but can also lower cloud resource costs.

In this guide, we’ll walk you through setting up self-hosted build agents step by step.

Generating a Personal Access Token (PAT)

To begin, you need to create a Personal Access Token (PAT) in Azure DevOps:

1. Click the gear icon next to your name and select Personal Access Tokens.
2. Click New Token to create a new one.
3. Set an appropriate expiration based on your requirements and define the necessary scopes (e.g., reading builds and releases, managing agent pools). Only grant permissions that are required to minimize security risks.

After creating the token, you will see a confirmation:

Creating an Agent Pool

Next, configure an agent pool within Azure DevOps:

1. Navigate to Project Settings and scroll to the Agent Pools section (found in the lower left).
2. Review the existing agent pools and click the option to add a new pool.
3. Select self-hosted as the pool type and assign a descriptive name (for example, "KodeKloud Customer").
4. Ensure that permissions are granted to all pipelines.

Setting Up the Agent

Once your agent pool is ready, it’s time to configure an agent on your local machine. The setup process varies slightly between Windows and Linux/Mac environments.

Windows Setup

Open a PowerShell prompt and execute the following commands:

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-win-x64-3.243.1.zip", "$PWD")
PS C:\agent> .\config.cmd
PS C:\agent> .\run.cmd

During configuration, you will be prompted for the server URL, the authentication type (press Enter to use PAT), and your personal access token. Next, specify the agent pool name (e.g., "KodeKloud Customer") and provide an agent name (such as "KodeKloud Agent 1"). You can also set a work folder for build artifacts and decide whether the agent should run as a service (press Enter to skip running as a service for now).

To manually start the agent later, run:

PS C:\agent> .\run.cmd

Linux/Mac Setup

For Linux and Mac environments, open a terminal and run:

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

This series of commands will extract the agent, guide you through the configuration, and start the agent once complete.

Verifying Agent Operation

After configuration, your agent appears in the Azure DevOps agent pool (for example, "KodeKloud Customer"). Initially, the agent might show as offline. To verify its operation, run the agent command:

PS C:\Users\jeremy\Downloads\agent> .\run.cmd

You should observe output similar to:

Scanning for tool capabilities.
Connecting to the server.
2024-09-11 05:24:11Z: Listening for Jobs

This confirms that the agent is online and ready to process jobs. When idle, it will continuously scan and wait for incoming tasks.

Troubleshooting and Maintenance

Keeping your self-hosted build agent operating smoothly involves regular troubleshooting and maintenance. Here are some common considerations:

1. Connection Problems:
   Ensure that your firewall settings allow outbound connections to Azure DevOps if the agent cannot connect.

2. Authentication Errors:
   Verify that your personal access token is valid and has the required permissions.

3. Missing Software Dependencies:
   Regularly update the host machine’s software dependencies to avoid build errors.

4. Routine Maintenance:
   Frequently audit both the agent software and security settings. For improved scalability and management, consider container-based agents if applicable.

By following these steps, you can set up and manage self-hosted build agents effectively, enjoying enhanced customization, performance improvements, and overall cost savings.

For more detailed guidance on Azure DevOps, visit the Azure DevOps Documentation.