Hosting a Windows Container Build Agent and Connecting It to Azure DevOps

Hosting a Windows Container Build Agent and Connecting It to Azure DevOps


Azure DevOps offers a great platform for automating your build and deployment pipelines. To take full advantage of its capabilities, you can set up a Windows container build agent that seamlessly integrates with Azure DevOps.

In this step-by-step guide, we will walk you through the process of creating a Windows container build agent and connecting it to Azure DevOps, enabling you to automate your development workflows efficiently.


Before we begin, ensure that you have the following prerequisites in place:

  1. Azure DevOps Account: You must have an Azure DevOps account. If you don’t have one, sign up at
  2. Azure DevOps Project: Create a new or use an existing Azure DevOps project.
  3. Docker Installed: You need to have Docker installed on your local machine. You can download and install Docker Desktop from Docker’s official website.

Step 1: Create a Dockerfile

  1. Open a text editor and create a Dockerfile for your Windows container build agent.
  2. Save the Dockerfile in a directory of your choice.
# Use the official Microsoft Windows Server Core image as the base image

# Set environment variables

# Create agent folder

# Download and extract the Azure Pipelines Agent package
ADD$env:AGENT_VERSION/vsts-agent-win-x64-$ $env:AGENT_FOLDER/

# Extract the agent package
RUN Expand-Archive -Path "$env:AGENT_FOLDER/vsts-agent-win-x64-$" -DestinationPath $env:AGENT_FOLDER

# Cleanup
RUN Remove-Item -Path "$env:AGENT_FOLDER/vsts-agent-win-x64-$" -Force

# Set the work directory

# Configure the agent
RUN ./config.cmd

# Start the agent
CMD ./run.cmd

Step 2: Build the Docker Image

  1. Open a command prompt or PowerShell window.
  2. Navigate to the directory containing your Dockerfile.
  3. Build the Docker image using the following command, replacing <your-image-name> with your desired image name.
  4. This command will create a Docker image based on the Dockerfile and tag it with your specified image name.
docker build -t <your-image-name> .

Step 3: Push the Docker Image to a Container Registry

  1. Log in to a container registry of your choice, such as Docker Hub or Azure Container Registry:
docker login <registry-url>

Step 4: Set up an Azure DevOps Build Pipeline

  1. In your Azure DevOps project, navigate to “Project Settings” and select “Agent Pools.”
  2. Create a new agent pool if necessary or use an existing one.
  3. In the agent pool settings, select “New agent.”
  4. Provide a name for the agent, and under “Operating System,” select “Windows.”
  5. Copy the agent registration script from Azure DevOps.
  6. Run the copied registration script on your Windows container host.
.\config.cmd --url --auth pat --token <Your-Personal-Access-Token> --pool <Agent-Pool-Name> --agent <Agent-Name> --windows

Step 5: Verify Agent Connection

  1. Go back to your Azure DevOps project and navigate to “Agent Pools.”
  2. Select the agent pool you configured earlier.
  3. You should see your Windows container agent listed as online. This indicates a successful connection.

Step 6: Configure and Run Pipelines

With your Windows container build agent connected to Azure DevOps, you can now create and configure CI/CD pipelines to automate your build and release workflows.

  1. Create a new pipeline in your Azure DevOps project.
  2. Define the pipeline YAML or use the visual editor to specify build and release tasks.
  3. Assign the agent pool and agent specifications to your pipeline.
  4. Save and run your pipeline.


Creating a Windows container build agent and connecting it to Azure DevOps allows you to automate your CI/CD workflows efficiently in a containerized environment.

By following the steps outlined in this guide, you can streamline your development processes and leverage the power of Azure DevOps for building, testing, and deploying your applications.


Hi, my name is Stephen Finchett. I have been a software engineer for over 30 years and worked on complex, business critical, multi-user systems for all of my career. For the last 15 years, I have been concentrating on web based solutions using the Microsoft Stack including ASP.Net, C#, TypeScript, SQL Server and running everything at scale within Kubernetes.