The Hosted Linux Preview Pool is deprecated and will be removed in December 2018. Learn more below.
If your pipelines are in Azure Pipelines, then you've got a convenient option to build and deploy using a Microsoft-hosted agent. With Microsoft-hosted agents, maintenance and upgrades are taken care of for you. Each time you run a pipeline, you get a fresh virtual machine. The virtual machine is discarded after one use.
For many teams this is the simplest way to build and deploy. You can try it first and see if it works for your build or deployment. If not, you can use a self-hosted agent.
You can try a Microsoft-hosted agent for no charge. If your build or release doesn't succeed, the issues will be reported in the logs.
Use a Microsoft-hosted agent
The Microsoft-hosted agent pool provides 5 virtual machine images to choose from:
- Ubuntu 16.04 (
- Visual Studio 2017 on Windows Server 2016 (
- macOS 10.13 (
- Windows Server 1803 (
win1803) - for running Windows containers
- Visual Studio 2015 on Windows Server 2012R2 (
|If your development team uses...||...then choose this image...||...or pool in web designer|
|Docker containers||ubuntu-16.04 or win1803||Hosted Ubuntu 1604 or Hosted Windows Container|
|Development tools on Ubuntu||ubuntu-16.04||Hosted Ubuntu 1604|
|Development tools on macOS||macOS-10.13 (see notes below)||Hosted macOS|
|.NET Core||ubuntu-1604 or vs2017-win2016||Hosted Ubuntu 1604 or Hosted VS2017|
|Visual Studio 2017||vs2017-win2016||Hosted VS2017|
|Visual Studio 2015||vs2015-win2012r2||Hosted|
YAML-based pipelines will default to the Microsoft-hosted agent pool. You simply need to specify which virtual machine image you want to use.
jobs: - job: Linux pool: vmImage: 'ubuntu-16.04' steps: - script: echo hello from Linux - job: macOS pool: vmImage: 'macOS-10.13' steps: - script: echo hello from macOS - job: Windows pool: vmImage: 'vs2017-win2016' steps: - script: echo hello from Windows
Notes on choosing "Hosted macOS"
This option affects where your data is stored. Learn more.
To disable the Hosted macOS agent pool for all projects, disable the
Hosted Agent checkbox under Admin settings > Agent pools > Hosted macOS.
To disable the Hosted macOS agent pool for a specific project, disable the
Hosted Agent checkbox under Project settings > Agent pools > Hosted macOS.
You can manually select from tool versions on macOS images. See below.
Software on Microsoft-hosted agents is updated once each month.
- Visual Studio 2017 on Windows Server 2016 (Hosted VS2017).
- Ubuntu 16.04 (Hosted Ubuntu 1604).
- Xcode 8, 9, and 10 on macOS 10.13 (Hosted macOS).
- Windows Server 1803 (Hosted Windows Container)
- Visual Studio 2015 on Windows Server 2012r2 (Hosted).
Capabilities and limitations
- Have the above software. You can also add software during your build or release using tool installer tasks.
- Provide at least 10 GB of storage for your source and build outputs.
- Can run jobs for up to 360 minutes (6 hours).
- Run on Microsoft Azure general purpose virtual machines Standard_DS2_v2
- Run as an administrator on Windows and a passwordless sudo user on Linux
Microsoft-hosted agents do not offer:
- The ability to log on.
- The ability to drop artifacts to a UNC file share.
- The ability to run XAML builds.
- Potential performance advantages that you might get by using self-hosted agents which might start and run builds faster. Learn more
If Microsoft-hosted agents don't meet your needs, then you can deploy your own self-hosted agents.
Avoid hard-coded references
When you use a Microsoft-hosted agent, always use variables to refer to the build environment and agent resources. For example, don't hardcode the drive letter or folder that contains the repository. The precise layout of the hosted agents is subject to change without warning.
Agent IP ranges
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. We recommend that you check back frequently 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.
We publish a weekly XML file listing IP ranges for Azure datacenters, broken out by region. This file is published every Wednesday (US Pacific time) with new planned IP ranges. The new IP ranges become effective the following Monday. Hosted agents run in the same region as your Azure DevOps organization. You can check your region by navigating to
https://<your_organization>.visualstudio.com/_admin/_home/settings. Under Account, you will see a field indicating your region.
This information is maintained by the Azure DevOps support team.
Q & A
I can't select a Microsoft-hosted agent and I can't queue my build or deployment. How do I fix this?
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.
I need more agents. What can I do?
A: 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 more minutes, or need to run additional builds or releases in parallel, then you can buy more parallel jobs for private projects.
I'm looking for the Microsoft-hosted XAML build controller. Where did it go?
The Microsoft-hosted XAML build controller is no longer supported. If you have an organization in which you still need to run XAML builds, you should set up a self-hosted build server and a self-hosted build controller.
We strongly recommend that you migrate your XAML builds to new builds.
How can I manually select versions of tools on the Hosted macOS agent?
To manually select a Xamarin SDK version to use on the Hosted macOS agent, before your Xamarin build task, execute this command line as part of your build, replacing the Mono version number 5.4.1 as needed (also replacing '.' characters with underscores: '_'). Choose the Mono version that is associated with the Xamarin SDK version that you need.
/bin/bash -c "sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh 5_4_1"
Mono versions associated with Xamarin SDK versions on the Hosted macOS agent can be found here.
Note that this command does not select the Mono version beyond the Xamarin SDK. To manually select a Mono version, see instructions below.
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 8.3.3 as needed:
/bin/bash -c "sudo xcode-select -s /Applications/Xcode_8.3.3.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, before your Mono build task, execute this script in each job of your build, replacing the Mono version number 5.4.1 as needed:
SYMLINK=5_4_1 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"
Hosted Linux Preview pool deprecation
We're deprecating the Hosted Linux Preview pool. We recommend that you begin moving your pipelines to the Hosted Ubuntu 1604 pool now. We plan to remove the Hosted Linux Preview from Azure Pipelines on December 1, 2018.
How do I move my builds?
You'll need to change the pool or queue. You might need to also change a few other things.
If you have scripts that assume that they're running as root, then you'll need to change them to use
If your pipeline assumes that its agent is running in a container, then you'll need to remove that assumption.
Point at the new pool
Pipelines that use
queue: 'Hosted Linux Preview' need to be changed to the new
queue has been split into two focused sections:
pool specifies which agent pool receives the build.
strategy specifies if and how the system should create multiple instances of the jobs you specify.
Example: Pool name only
# Before queue: 'Hosted Linux Preview' # After pool: vmImage: 'ubuntu-16.04'
Example: Pool name with a matrix
# Before queue: 'Hosted Linux Preview' matrix: entry1: var: value1 entry2: var: value2 # After ## The matrix syntax has not changed, but it has moved under a `strategy` keyword pool: vmImage: 'ubuntu-16.04' strategy: matrix: entry1: var: value1 entry2: var: value2
Example: Pool name with a matrix and parallelism
# Before queue: 'Hosted Linux Preview' parallel: 2 matrix: entry1: var: value1 entry2: var: value2 # After ## The keyword `parallel` has been replaced by `maxParallel` and moved under the strategy node pool: vmImage: 'ubuntu-16.04' strategy: maxParallel: 2 matrix: entry1: var: value1 entry2: var: value2
Remove user assumptions
If you run tools that require root access, then you'll instead need to run them using
For example, if you have a script like this:
apt-get update && apt-get install foo
Then you'll need to update it to invoke
sudo apt-get update && sudo apt-get install foo
Remove container assumptions
This is not common.
If your pipeline works with Docker containers, then you may be running commands to account for the agent itself running in a container. On the Hosted Ubuntu 1604 pool, the agent no longer runs in a container. Typically, this means you can remove parameters or even entire commands from your Docker interactions.
Why is this changing?
The Hosted Linux Preview pool ran agents inside a container. If you weren't aware that the agent was in a container, your pipelines would fail in surprising ways if you tried to operate on containers. For example, you could successfully instantiate another container, but because the agent and new containers weren't networked together, you couldn't communicate between them.
The Hosted Ubuntu 1604 pool uses a more typical model that matches the other hosted pools. The agent runs on the host VM. When you start a container from the agent, the host is networked to the container automatically.
What will happen if I don't move?
On December 1, 2018, your pipelines that attempt to queue for the Hosted Linux Preview pool will fail.