Microsoft-hosted agents

Azure Pipelines

Note

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.

Tip

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 (ubuntu-16.04)
  • Visual Studio 2017 on Windows Server 2016 (vs2017-win2016)
  • macOS 10.13 (macOS-10.13)
  • Windows Server 1803 (win1803) - for running Windows containers
  • Visual Studio 2015 on Windows Server 2012R2 (vs2015-win2012r2)
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-16.04 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

Software on Microsoft-hosted agents is updated once each month.

Capabilities and limitations

Microsoft-hosted agents:

  • 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:

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.

Note

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://dev.azure.com/<your_organization>/_settings/overview. Under Organization information, 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.

Tip

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?

Xamarin

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.

Xcode

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.

Mono

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

The Hosted Linux Preview pool has been deprecated since December 1, 2018, and is being removed in waves. You must move your pipelines to the Hosted Ubuntu 1604 pool.

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 sudo. 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 pool syntax. queue has been split into two focused sections: pool and strategy. 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 sudo. 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:

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.

Videos