Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Azure DevOps Services
Microsoft-hosted agents are only available with Azure DevOps Services, which is hosted in the cloud. You cannot use Microsoft-hosted agents or the Azure Pipelines agent pool with on-premises TFS or Azure DevOps Server. With these on-premises versions, you must use self-hosted agents.
Important
Select the version of this article that corresponds to your platform and version. The version selector is above the table of contents. Look up your Azure DevOps platform and version.
If your pipelines are in Azure Pipelines, then you've got a convenient option to run your jobs using a Microsoft-hosted agent. With Microsoft-hosted agents, maintenance and upgrades are taken care of for you. You always get the latest version of the VM image you specify in your pipeline. Each time you run a pipeline, you get a fresh virtual machine for each job in the pipeline. The virtual machine is discarded after one job (which means any change that a job makes to the virtual machine file system, such as checking out code, will be unavailable to the next job). Microsoft-hosted agents can run jobs directly on the VM or in a container.
Azure Pipelines provides a predefined agent pool named Azure Pipelines with Microsoft-hosted agents.
For many teams this is the simplest way to run your jobs. You can try it first and see if it works for your build or deployment. If not, you can use scale set agents or a self-hosted agent.
Tip
You can try a Microsoft-hosted agent for no charge.
The Azure Pipelines agent pool offers several virtual machine images to choose from, each including a broad range of tools and software.
Image | Classic Editor Agent Specification | YAML VM Image Label | Included Software |
---|---|---|---|
Windows Server 2022 with Visual Studio 2022 | windows-2022 | windows-latest OR windows-2022 |
Link |
Windows Server 2019 with Visual Studio 2019 | windows-2019 | windows-2019 |
Link |
Ubuntu 24.04 | ubuntu-24.04 | ubuntu-24.04 |
Link |
Ubuntu 22.04 | ubuntu-22.04 | ubuntu-latest OR ubuntu-22.04 |
Link |
Ubuntu 20.04 | ubuntu-20.04 | ubuntu-20.04 |
Link |
macOS 15 Sequoia preview | macOS-15 | macOS-15 |
Link |
macOS 14 Sonoma | macOS-14 | macOS-latest OR macOS-14 |
Link |
macOS 13 Ventura | macOS-13 | macOS-13 |
Link |
The default agent image for classic build pipelines is windows-2019, and the default agent image for YAML build pipelines is ubuntu-latest
. For more information, see Designate a pool in your pipeline.
You can see the installed software for each hosted agent by choosing the Included Software link in the table. When using macOS images, you can manually select from tool versions. Read more.
ubuntu-latest
images use ubuntu-22.04
.windows-latest
images use windows-2022
.macOS-latest
images use macOS-11
.macOS-10.14
)vs2015-win2012r2
)macOS-10.13
)win1803
)Customers are encouraged to migrate to newer versions or a self-hosted agent.
For more information and instructions on how to update your pipelines that use those images, see Removing older images in Azure Pipelines hosted pools.
Note
The Azure Pipelines hosted pool replaces the previous hosted pools that had names that mapped to the corresponding images. Any jobs you had in the previous hosted pools are automatically redirected to the correct image in the new Azure Pipelines hosted pool. In some circumstances, you may still see the old pool names, but behind the scenes the hosted jobs are run using the Azure Pipelines pool. For more information about this update, see the Single hosted pool release notes from the July 1 2019 - Sprint 154 release notes.
Important
To request additional software to be installed on Microsoft-hosted agents, don't create a feedback request on this document or open a support ticket. Instead, open an issue on our repository, where we manage the scripts to generate various images.
To identify pipelines that are using a deprecated image, browse to the following location in your organization: https://dev.azure.com/{organization}/{project}/_settings/agentqueues
, and filter on the image name to check. The following example checks the vs2017-win2016
image.
You can also query job history for deprecated images across projects using the script located here, as shown in the following example.
./QueryJobHistoryForRetiredImages.ps1 -accountUrl https://dev.azure.com/{org} -pat {pat}
In YAML pipelines, if you do not specify a pool, pipelines default to the Azure Pipelines agent pool. You simply need to specify which virtual machine image you want to use.
jobs:
- job: Linux
pool:
vmImage: 'ubuntu-latest'
steps:
- script: echo hello from Linux
- job: macOS
pool:
vmImage: 'macOS-latest'
steps:
- script: echo hello from macOS
- job: Windows
pool:
vmImage: 'windows-latest'
steps:
- script: echo hello from Windows
Note
The specification of a pool can be done at multiple levels in a YAML file. If you notice that your pipeline is not running on the expected image, make sure that you verify the pool specification at the pipeline, stage, and job levels.
When you use a Microsoft-hosted agent, always use variables to refer to the build environment and agent resources. For example, don't hard-code the drive letter or folder that contains the repository. The precise layout of the hosted agents is subject to change without warning.
Microsoft-hosted agents that run Windows and Linux images are provisioned on Azure general purpose virtual machines with a 2 core CPU, 7 GB of RAM, and 14 GB of SSD disk space. These virtual machines are co-located in the same geography as your Azure DevOps organization.
Agents that run macOS images are provisioned on Mac pros with a 3 core CPU, 14 GB of RAM, and 14 GB of SSD disk space. These agents always run in the US irrespective of the location of your Azure DevOps organization. If data sovereignty is important to you and if your organization is not in the US, then you should not use macOS images. Learn more.
All of these machines have at least 10 GB of free disk space available for your pipelines to run. This free space is consumed when your pipeline checks out source code, downloads packages, pulls docker images, or generates intermediate files.
Important
We cannot honor requests to increase disk space on Microsoft-hosted agents, or to provision more powerful machines. If the specifications of Microsoft-hosted agents do not meet your needs, then you should consider self-hosted agents or scale set agents or Managed DevOps Pools.
In some setups, you may need to know the range of IP addresses where agents are deployed. For instance, if you need to grant the hosted agents access through a firewall, you may wish to restrict that access by IP address. Because Azure DevOps uses the Azure global network, IP ranges vary over time. Microsoft publishes a weekly JSON file listing IP ranges for Azure datacenters, broken out by region. This file is updated weekly with new planned IP ranges. Only the latest version of the file is available for download. If you need previous versions, you must download and archive them each week as they become available. The new IP ranges become effective the following week. We recommend that you check back frequently (at least once every week) to ensure you keep an up-to-date list. If agent jobs begin to fail, a key first troubleshooting step is to make sure your configuration matches the latest list of IP addresses. The IP address ranges for the hosted agents are listed in the weekly file under AzureCloud.<region>
, such as AzureCloud.westus
for the West US region.
Your hosted agents run in the same Azure geography as your organization. Each geography contains one or more regions. While your agent may run in the same region as your organization, it is not guaranteed to do so. To obtain the complete list of possible IP ranges for your agent, you must use the IP ranges from all of the regions that are contained in your geography. For example, if your organization is located in the United States geography, you must use the IP ranges for all of the regions in that geography.
To determine your geography, navigate to https://dev.azure.com/<your_organization>/_settings/organizationOverview
, get your region, and find the associated geography from the Azure geography table. Once you have identified your geography, use the IP ranges from the weekly file for all regions in that geography.
Important
You cannot use private connections such as ExpressRoute or VPN to connect Microsoft-hosted agents to your corporate network. The traffic between Microsoft-hosted agents and your servers will be over public network.
AzureCloud.<region>
, such as AzureCloud.westus
. You can map the names of the regions from the Azure Geography list to the format used in the weekly file by reviewing the region names passed to the constructor of the regions defined in the source code for the Region class, from the Azure Management Libraries for .NET.
Note
Since there is no API in the Azure Management Libraries for .NET to list the regions for a geography, you must list them manually as shown in the following example.
Note
Due to capacity restrictions, some organizations in the Brazil South or West Europe regions may occasionally see their hosted agents located outside their expected geography. In these cases, in addition to including the IP ranges for all the regions in your geography as described in the previous section, additional IP ranges must be included for the regions in the capacity fallback geography.
If your organization is in the Brazil South region, your capacity fallback geography is United States.
If your organization is in the West Europe region, the capacity fallback geography is France.
Our Mac IP ranges are not included in the Azure IPs above, as they are hosted in GitHub's macOS cloud. IP ranges can be retrieved using the GitHub metadata API using the instructions provided here.
In the following example, the hosted agent IP address ranges for an organization in the West US region are retrieved from the weekly file. Since the West US region is in the United States geography, the IP addresses for all regions in the United States geography are included. In this example, the IP addresses are written to the console.
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
namespace WeeklyFileIPRanges
{
class Program
{
// Path to the locally saved weekly file
const string weeklyFilePath = @"C:\MyPath\ServiceTags_Public_20230904.json";
static void Main(string[] args)
{
// United States geography has the following regions:
// Central US, East US, East US 2, East US 3, North Central US,
// South Central US, West Central US, West US, West US 2, West US 3
// This list is accurate as of 9/8/2023
List<string> USGeographyRegions = new List<string>
{
"centralus",
"eastus",
"eastus2",
"eastus3",
"northcentralus",
"southcentralus",
"westcentralus",
"westus",
"westus2",
"westus3"
};
// Load the weekly file
JObject weeklyFile = JObject.Parse(File.ReadAllText(weeklyFilePath));
JArray values = (JArray)weeklyFile["values"];
foreach (string region in USGeographyRegions)
{
string tag = $"AzureCloud.{region}";
Console.WriteLine(tag);
var ipList =
from v in values
where tag.Equals((string)v["name"], StringComparison.OrdinalIgnoreCase)
select v["properties"]["addressPrefixes"];
foreach (var ip in ipList.Children())
{
Console.WriteLine(ip);
}
}
}
}
}
Microsoft-hosted agents can't be listed by service tags. If you're trying to grant hosted agents access to your resources, you'll need to follow the IP range allow listing method.
Microsoft-hosted agents run on secure Azure platform. However, you must be aware of the following security considerations.
Microsoft-hosted agents:
cgroup
that offers 6 GB of physical memory and 13 GB of total memory.Microsoft-hosted agents do not offer:
If Microsoft-hosted agents don't meet your needs, then you can deploy your own self-hosted agents or use scale set agents or Managed DevOps Pools.
You can see the installed software for each hosted agent by choosing the Included Software link in the Software table.
Note
By default, the Windows agent uses the version of Git that is bundled with the agent software. Microsoft recommends using the version of Git that is bundled with the agent, but you have several options to override this default behavior and use the version of Git that the agent machine has installed in the path.
System.PreferGitFromPath
to true
in your pipelines.System.PreferGitFromPath=true
line to the file. For more information, see How do I set different environment variables for each individual agent?To see the version of Git used by a pipeline, you can look at the logs for a checkout
step in your pipeline, as shown in the following example.
Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1
More information about the versions of software included on the images can be found at Guidelines for what's installed.
Images are typically updated weekly. You can check the status badges which are in the format 20200113.x
where the first part indicates the date the image was updated.
You can let us know by filing a GitHub issue by choosing the Included Software links in the Use a Microsoft-hosted agent table.
You can also use a self-hosted agent that includes the exact versions of software that you need. For more information, see Self-hosted agents.
We can't increase the memory, processing power, or disk space for Microsoft-hosted agents, but you can use self-hosted agents or scale set agents or Managed DevOps Pools hosted on machines with your desired specifications.
Microsoft-hosted agents are only available in Azure Pipelines and not in TFS or Azure DevOps Server.
By default, all project contributors in an organization have access to the Microsoft-hosted agents. But, your organization administrator may limit the access of Microsoft-hosted agents to select users or projects. Ask the owner of your Azure DevOps organization to grant you permission to use a Microsoft-hosted agent. See agent pool security.
If your pipeline has recently become slower, review our status page for any outages. We could be having issues with our service. Or else, review any changes that you made in your application code or pipeline. Your repository size during check-out might have increased, you may be uploading larger artifacts, or you may be running more tests.
If you are just setting up a pipeline and are comparing the performance of Microsoft-hosted agents to your local machine or a self-hosted agent, then note the specifications of the hardware that we use to run your jobs. We are unable to provide you with bigger or powerful machines. You can consider using self-hosted agents or scale set agents or Managed DevOps Pools if this performance is not acceptable.
All Azure DevOps organizations are provided with several free parallel jobs for open-source projects, and one free parallel job and limited minutes each month for private projects. If you need additional minutes or parallel jobs for your open-source project, contact support. If you need additional minutes or parallel jobs for your private project, then you can buy more.
Your self-hosted agent probably has all the right dependencies installed on it, whereas the same dependencies, tools, and software are not installed on Microsoft-hosted agents. First, carefully review the list of software that is installed on Microsoft-hosted agents by following the link to Included software in the table above. Then, compare that with the software installed on your self-hosted agent. In some cases, Microsoft-hosted agents may have the tools that you need (for example, Visual Studio), but all of the necessary optional components may not have been installed. If you find differences, then you have two options:
You can create a new issue on the repository, where we track requests for additional software. Contacting support can't help you set up new software on Microsoft-hosted agents.
You can use self-hosted agents or scale set agents or Managed DevOps Pools. With these agents, you are fully in control of the images that are used to run your pipelines.
Your local machine probably has all the right dependencies installed on it, whereas the same dependencies, tools, and software are not installed on Microsoft-hosted agents. First, carefully review the list of software that is installed on Microsoft-hosted agents by following the link to Included software in the table above. Then, compare that with the software installed on your local machine. In some cases, Microsoft-hosted agents may have the tools that you need (e.g., Visual Studio), but all of the necessary optional components may not have been installed. If you find differences, then you have two options:
You can create a new issue on the repository, where we track requests for additional software. This is your best bet for getting new software installed. Contacting support will not help you with setting up new software on Microsoft-hosted agents.
You can use self-hosted agents or scale set agents or Managed DevOps Pools. With these agents, you are fully in control of the images that are used to run your pipelines.
Microsoft-hosted agents only have 10 GB of disk space available for running your job. This space is consumed when you check out source code, when you download packages, when you download docker images, or when you produce intermediate files. Unfortunately, we cannot increase the free space available on Microsoft-hosted images. You can restructure your pipeline so that it can fit into this space. Or, you can consider using self-hosted agents or scale set agents or Managed DevOps Pools.
See the section Agent IP ranges
If you refer to the server by its DNS name, then make sure that your server is publicly accessible on the Internet through its DNS name. If you refer to your server by its IP address, make sure that the IP address is publicly accessible on the Internet. In both cases, ensure that any firewall in between the agents and your corporate network has the agent IP ranges allowed.
If you get an SAS error code, it is most likely because the IP address ranges from the Microsoft-hosted agents aren't permitted due to your Azure Storage rules. There are a few workarounds:
If you use the Xcode task included with Azure Pipelines and TFS, you can select a version of Xcode in that task's properties. Otherwise, to manually set the Xcode version to use on the Hosted macOS agent pool, before your xcodebuild
build task, execute this command line as part of your build, replacing the Xcode version number 13.2 as needed:
/bin/bash -c "sudo xcode-select -s /Applications/Xcode_13.2.app/Contents/Developer"
Xcode versions on the Hosted macOS agent pool can be found here.
To manually select a Mono version to use on the Hosted macOS agent pool, execute this script in each job of your build before your Mono build task, specifying the symlink with the required Mono version:
SYMLINK=<symlink>
MONOPREFIX=/Library/Frameworks/Mono.framework/Versions/$SYMLINK
echo "##vso[task.setvariable variable=DYLD_FALLBACK_LIBRARY_PATH;]$MONOPREFIX/lib:/lib:/usr/lib:$DYLD_LIBRARY_FALLBACK_PATH"
echo "##vso[task.setvariable variable=PKG_CONFIG_PATH;]$MONOPREFIX/lib/pkgconfig:$MONOPREFIX/share/pkgconfig:$PKG_CONFIG_PATH"
echo "##vso[task.setvariable variable=PATH;]$MONOPREFIX/bin:$PATH"
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Host your own build agent in Azure Pipelines - Training
Work with guidance from the Space Game web team to set up your build agent running on-premises or on an Azure virtual machine running in the cloud.
Documentation
Create and manage agent pools - Azure Pipelines
Learn about organizing agents into pools for builds and releases in Azure Pipelines and Team Foundation Server
Azure Pipelines Agents - Azure Pipelines
Learn about building your code or deploying your software using agents in Azure Pipelines.
Deploy a build and release agent on macOS - Azure Pipelines
Learn how to deploy a macOS agent to build and deploy your iOS application for Azure Pipelines and Team Foundation Server (TFS)