Edit

Share via

Azure Pipelines agents

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

You need at least one agent to build your code or deploy your software by using Azure Pipelines. As your code base and team grow, you need multiple agents.

When your pipeline runs, the system begins one or more jobs. An agent is computing infrastructure with installed agent software that runs one job at a time.

Azure Pipelines provides several different types of agents.

Agent type Description Availability
Microsoft-hosted agents Agents hosted and managed by Microsoft. Azure DevOps Services
Self-hosted agents Agents that you configure and manage that are hosted on your virtual machines (VMs). Azure DevOps Services, Azure DevOps Server
Managed DevOps Pools agents Managed DevOps Pools is a fully managed service. Virtual machines or containers that power the agents live in a Microsoft Azure subscription and not in your own Azure subscription. Azure DevOps Services
Azure Virtual Machine Scale Sets agents A form of self-hosted agents that uses Azure Virtual Machine Scale Sets and can be autoscaled to meet demands.

If you're considering using autoscalable, self-hosted agent pools, we recommend that you consider Managed DevOps Pools. For more information, see Compare Managed DevOps Pools with Azure Virtual Machine Scale Sets agents and Managed DevOps Pools overview.		 Azure DevOps Services

You can run jobs directly on the host machine of the agent or in a container.

Microsoft-hosted agents

If your pipelines are in Azure Pipelines, you can conveniently run your jobs by using a Microsoft-hosted agent. With Microsoft-hosted agents, maintenance and upgrades happen automatically.

You always have 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. Any change that a job makes to the virtual machine file system, such as checking out code, is unavailable on 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 process is the simplest way to run your jobs. You can try it first to see if it works for your build or deployment. If not, you can use Virtual Machine Scale Sets agents or a self-hosted agent.

Tip

You can try a Microsoft-hosted agent for no charge.

Learn more about Microsoft-hosted agents.

Self-hosted agents

A self-hosted agent is an agent that you set up to run jobs and manage yourself. You can use self-hosted agents in Azure Pipelines or Azure DevOps Server. Self-hosted agents give you more control to install dependent software that you need for your builds and deployments. Also, machine-level caches and configuration persist from run to run, which can boost speed.

Although multiple agents can be installed per machine, we strongly recommend that you install only one agent per machine. When you install two or more agents, it might adversely affect performance and the result of your pipelines.

Tip

Before you install a self-hosted agent, you might want to see if a Microsoft-hosted agent pool works for you. In many cases, a Microsoft-hosted agent pool is the simplest way to get started. Give it a try.

You can install the agent on Linux, macOS, and Windows machines. You can also install the agent on a Docker container. For more information about installing a self-hosted agent, see:

On macOS, you need to clear the special attribute on the download archive to prevent the macOS Gatekeeper protection from displaying for each assembly in the TAR file when ./config.sh is run. The following command clears the extended attribute on the file:

xattr -c vsts-agent-osx-x64-V.v.v.tar.gz  ## replace V.v.v with the version in the filename downloaded.
 
# then unpack the gzip tar file normally:

tar xvfz vsts-agent-osx-x64-V.v.v.tar.gz

After you install the agent on a machine, you can install any other software on that machine that your jobs require.

Note

Agents are widely backward compatible. Any version of the agent should be compatible with any Azure DevOps version, as long as Azure DevOps doesn't demand a higher version of the agent.

We support only the most recent version of the agent, because that is the only version guaranteed to have all up-to-date patches and bug fixes.

Node.js runner versions

The agent ships with several versions of Node.js libraries to support target tasks that use different Node.js handlers.

All official Azure DevOps tasks use Node.js 20 library as a universal handler. However, customers might still use custom tasks that use the end-of-support Node.js 6, Node.js 10, or Node.js 16 library. To support backward compatibility with a node that reached end of support, we provide the following self-service methods so that you can manually install the designated Node.js runner:

  • Manually install the Node.js 6 or Node.js 10 runner. For more information, see Node.js runner support.

  • Use the NodeTaskRunnerInstaller@0 task in your pipelines that require the outdated Node.js 6 or Node.js 10 library.

  • Install an agent package that includes Node.js 6 and Node.js 10 libraries.

    Azure Pipelines provides two versions of agent packages:

    • vsts-agent-\: Packages that support Node.js 6 and Node.js 10 libraries.
    • pipelines-agent-\: Packages that don't support Node.js 6 and Node.js 10 libraries. In the future, this version of the package becomes the default agent package.

    If your tasks don't require the Node.js 6 or Node.js 10 library, and you don't want to install the Node.js 6 or Node.js 10 library on your agent machine, you can install the agent from this documentation, under Alternate Agent Downloads.

Azure Virtual Machine Scale Sets agents

Azure Virtual Machine Scale Sets agents are a form of self-hosted agents that can be autoscaled to meet your demands. This elasticity reduces your need to run dedicated agents all the time. Unlike Microsoft-hosted agents, you have flexibility over the size and image of machines on which agents run.

Azure Pipelines manages the scaling of your agents for you. Specify the following factors:

  • A virtual machine scale set
  • The number of agents to keep on standby
  • A maximum number of virtual machines in the scale set

For more information, see Azure Virtual Machine Scale Sets agents.

Managed DevOps Pools agents

Managed DevOps Pools empowers development teams to quickly and easily spin up Azure DevOps agent pools that are tailored to a team's specific needs.

Managed DevOps Pools:

  • Implements security best practices.
  • Provides ways to balance cost and performance.
  • Provides paths for the most common scenarios.
  • Significantly reduces the time it takes to create and maintain custom pools.

Managed DevOps Pools is an evolution of Azure Virtual Machine Scale Sets agent pools. It simplifies custom pool creation even further by improving the scalability and reliability of custom pools. Managed DevOps Pools is a fully managed service. The virtual machines or containers that power agents live in a Microsoft Azure subscription and not in your own Azure subscription, similar to Azure Virtual Machine Scale Sets agent pools. For more information, see the Managed DevOps Pools documentation.

Parallel jobs

The concept of parallel jobs represents the number of jobs that you can run at the same time in your organization. If your organization has a single parallel job, you can run a single job at a time in your organization. Any other concurrent jobs are queued until the first job finishes. To run two jobs at the same time, you need two parallel jobs. In Azure Pipelines, you can run parallel jobs on Microsoft-hosted infrastructure or on your own (self-hosted) infrastructure.

Microsoft provides a free tier of service by default in every organization that includes at least one parallel job. Depending on the number of concurrent pipelines you need to run, you might need more parallel jobs to use multiple Microsoft-hosted or self-hosted agents at the same time. For more information on parallel jobs and different free tiers of service, see Parallel jobs in Azure Pipelines.

You might need more parallel jobs to use multiple agents at the same time:

Important

Starting with Azure DevOps Server 2019, you don't pay for self-hosted concurrent jobs in releases. You're only limited by the number of agents that you have.

Capabilities

Every self-hosted agent has a set of capabilities that indicate what it can do. Capabilities are name/value pairs that are either:

  • Capabilities that the agent software discovers, called system capabilities.
  • Capabilities that you define, called user capabilities.

The agent software automatically determines various system capabilities. These capabilities include the name of the machine, type of operating system, and versions of certain software installed on the machine. Also, environment variables defined in the machine automatically appear in the list of system capabilities.

When you store environment variables as capabilities, the stored capability values are used to set the environment variables when an agent runs. Also, when you make any changes to environment variables while the agent is running, they aren't picked up and used by any task. If you don't want sensitive environment variables that change to be stored as capabilities, you can direct the agent to ignore them. Set the VSO_AGENT_IGNORE environment variable, with a comma-delimited list of variables to ignore. For example, PATH is a critical variable that you might want to ignore if you're installing software.

When you author a pipeline, you specify certain demands of the agent. The system sends the job only to agents that have capabilities that match the demands specified in the pipeline. As a result, agent capabilities allow you to direct jobs to specific agents.

Demands and capabilities are designed for use with self-hosted agents so that jobs can be matched with an agent that meets the requirements of the job. When you use Microsoft-hosted agents, you select an image for the agent that matches the requirements of the job. Although it's possible to add capabilities to a Microsoft-hosted agent, you don't need to use capabilities with Microsoft-hosted agents.

Configure demands

To add a demand to your YAML build pipeline, add the demands: line to the pool section.

pool:
  name: Default
  demands: SpecialSoftware # exists check for SpecialSoftware

You can check for the existence of a capability or make a comparison with the value of a capability. For more information, see YAML schema - Demands.

Configure agent capabilities

You can view agent details, including version and system capabilities, and manage its user capabilities. Go to Agent pools and select the Capabilities tab for the desired agent.

  1. In your web browser, go to Agent pools:

    1. Sign in to your organization (https://dev.azure.com/{yourorganization}).

    2. Select Azure DevOps > Organization settings.

      Screenshot that shows how to select Organization settings.

    3. Select Agent pools.

      Screenshot that shows how to select the Agent pools tab.

    1. Sign in to your project collection (http://your-server/DefaultCollection).

    2. Select Azure DevOps > Collection settings.

      Screenshot that shows how to select Collection settings.

    3. Select Agent pools.

      Select Agent pools.

    Screenshot that shows how to go to and select Agent pools.

  2. Go to the Capabilities tab:

    1. From the Agent pools tab, select the desired agent pool.

      From Agent pools, select the desired agent pool.

    2. Select Agents and choose the desired agent.

      Select Agents and choose the agent.

    3. Choose the Capabilities tab.

      Choose the Capabilities tab.

      Note

      Microsoft-hosted agents don't display system capabilities. For a list of software installed on Microsoft-hosted agents, see Use a Microsoft-hosted agent.

    1. From the Agent pools tab, select the desired pool.

      Select the desired pool.

    2. Select Agents and choose the desired agent.

      Select Agents and choose the desired agent.

    3. Choose the Capabilities tab.

      Agent capabilities tab.

  3. To register a new capability with the agent, select Add a new capability.

Tip

After you install new software on a self-hosted agent, you must restart the agent for the new capability to show up. For more information, see Restart Windows agent, Restart Linux agent, and Restart Mac agent.

Communication

Communication with Azure Pipelines

Communication with Azure DevOps Server

The agent communicates with Azure Pipelines or Azure DevOps Server. It determines which job it needs to run and reports the logs and job status. The agent always initiates this communication.

All the messages from the agent to Azure Pipelines or Azure DevOps Server happen over HTTP or HTTPS, depending on how you configure the agent. This pull model allows you to configure the agent to different topologies, as shown in the following examples.

Graphic that shows agent topologies in on-premises installations.

Graphic that shows agent topologies in Azure DevOps Services.

Here's a common communication pattern between the agent and Azure Pipelines or Azure DevOps Server:

  1. The user registers an agent with Azure Pipelines or Azure DevOps Server by adding it to an agent pool. To register an agent in that agent pool, you need to have the Agent pool administrator role. The Agent pool administrator role is needed only at the time of registration and isn't persisted on the agent. It isn't used in any further communication between the agent and Azure Pipelines or Azure DevOps Server.

    After registration is complete, the agent downloads a listener OAuth token and uses it to listen to the job queue.

  2. The agent listens to see if a new job request is posted in the job queue in Azure Pipelines or Azure DevOps Server by using an HTTP long poll. When a job is available, the agent downloads the job and a job-specific OAuth token. Azure Pipelines or Azure DevOps Server generates a short-lived token for the scoped identity specified in the pipeline.

    The agent uses the token to access or modify resources on Azure Pipelines or Azure DevOps Server within that job. For example, it uses the token to access source code or upload test results.

  3. The agent discards the job-specific OAuth token after the job is completed, and then checks if there's a new job request using the listener OAuth token.

The payload of the messages exchanged between the agent and Azure Pipelines or Azure DevOps Server are secured by using asymmetric encryption.

Each agent has a public-private key pair, and the public key is exchanged with the server during registration. The server uses the public key to encrypt the payload of the job before it sends it to the agent. The agent decrypts the job content by using its private key.

This method secures secrets stored in pipelines or variable groups when exchanged with the agent.

Note

The agent provides support for UTF-8 client encoding output. However, if your system doesn't use UTF-8 encoding, you might encounter some problems with log output. For example, logs might contain characters that your system’s encoding doesn't recognize, so they might appear to be garbled or missing symbols.

Communication to deploy to target servers

When you use the agent to deploy artifacts to a set of servers, it must have "line of sight" connectivity to those servers. Microsoft-hosted agent pools, by default, have connectivity to Azure websites and servers that run in Azure.

If your Azure resources run in an Azure virtual network, you can get the Agent IP ranges where Microsoft-hosted agents are deployed. Then, you can configure the firewall rules for your Azure virtual network to allow access by the agent.

If your on-premises environments don't have connectivity to a Microsoft-hosted agent pool, which is typically the case due to intermediate firewalls, you need to manually configure self-hosted agents on on-premises computers. The agents must have connectivity to the target on-premises environments, and access to the internet to connect to Azure Pipelines or Azure DevOps Server. This process is demonstrated in the following schematic:

Graphic that shows agent connectivity for on-premises environments.

Authentication

To register an agent, you need to be a member of the administrator role in the agent pool. The identity of agent pool administrator is needed only at the time of registration and isn't persisted on the agent. It isn't used in any subsequent communication between the agent and Azure Pipelines or Azure DevOps Server. To configure the agent, you also must be a local administrator on the server.

When you register an agent, select from the following authentication types. The agent setup process prompts you for the specific additional information required for each authentication type. For more information, see Self-hosted agent authentication options.

  • Personal access token.
  • Alternate: Connect to Azure DevOps Server by using Basic authentication. When you select Alternate, you're prompted for your credentials.

Additionally, Windows agents have the following two authentication options on Azure DevOps Server.

  • Negotiate: Connect to Azure DevOps Server as a user other than the signed-in user via a Windows authentication scheme (for example, New Technology LAN Manager (NTLM) or Kerberos). After you select Negotiate, you're prompted for credentials.
  • Integrated: (Default) Connect a Windows agent to Azure DevOps Server by using the credentials of the signed-in user via a Windows authentication scheme (for example, NTLM or Kerberos). You won't be prompted for credentials after you select this method.

Important

You must configure your server to support the authentication method to use Alternate, Negotiate, or Integrated authentication.

The authentication method that you use to register the agent is used only during agent registration. To learn more about how agents communicate with Azure Pipelines after registration, see Communication with Azure Pipelines or Azure DevOps Server.

Interactive vs. service

You can run your self-hosted agent as either a service or an interactive process.

After you configure the agent, we recommend that you first try it in interactive mode to make sure it works. Then, for production use, we recommend that you run the agent in one of the following modes so that it reliably remains in a running state. These modes also ensure that the agent starts automatically if the machine is restarted.

  • As a service: You can use the service manager of the operating system to manage the lifecycle of the agent. The experience to autoupgrade the agent is better when you run the agent as a service.

  • As an interactive process with automatic sign in enabled: In some cases, you might need to run the agent interactively for production use (for example, to run UI tests). When you configure an agent to run in this mode, the screen saver is disabled. Some domain policies might prevent you from enabling automatic sign in or disabling the screen saver. In such cases, you might need to seek an exemption from the domain policy, or run the agent on a workgroup computer where the domain policies don't apply.

    Note

    There are security risks when you enable automatic sign in or disable the screen saver. Other users might be able to access the computer and use the account that automatically signs in. If you configure the agent to run this way, you must ensure the computer is physically protected (for example, located in a secure facility).

    If you use a remote desktop to access a computer on which an agent is running with automatic sign in, closing the remote desktop causes the computer to lock. Any UI tests that run on this agent might fail. To avoid this issue, use the tscon command to disconnect from the remote desktop. For example:

    %windir%\System32\tscon.exe 1 /dest:console

Agent account

Whether you run an agent as a service or interactively, you can choose which computer account you use to run the agent. The choice of agent account depends solely on the needs of the tasks that run in your build and deployment jobs.

For example, to run tasks by using Windows authentication to access an external service, the agent must run by using an account with access to that service. However, if you're running UI tests such as Selenium or Coded UI tests that require a browser, the browser opens in the context of the agent account.

On Windows, we recommend that you use a service account like Network Service or Local Service. These accounts permissions are restricted and their passwords don't expire, so the agent requires less management over time.

These credentials are different from the credentials that you use when you register the agent with Azure Pipelines or Azure DevOps Server.

Agent version and upgrades

We update the agent software every few weeks in Azure Pipelines. We indicate the agent version in the format {major}.{minor}. For instance, if the agent version is 2.1, then the major version is 2 and the minor version is 1.

We keep Microsoft-hosted agents up to date. If the newer version of the agent is only different in the minor version, Azure Pipelines can automatically update self-hosted agents. The default setting is enabled. You can configure this setting in Agent pools by selecting your agent, and then selecting Settings. An upgrade is requested when a platform feature or one of the tasks in the pipeline requires a newer version of the agent.

If you run a self-hosted agent interactively, or if there's a newer major version of the agent available, then you might have to manually upgrade the agents. You can upgrade the agents from the Agent pools tab under your organization. Pipelines can't run without a compatible agent.

To update self-hosted agents

  1. Go to Project settings > Agent pools.

    Screenshot that shows how to find and select Agent pools.

  2. Select your agent pool, and then select Update all agents.

    Screenshot that shows how to select Update all agents.

    You can also update agents individually by selecting Update agent from the ... menu.

    Screenshot that shows how to select Update agent.

  3. Select Update to confirm.

    Screenshot that shows how to select Update to confirm.

  4. An update request is queued for each agent in the pool, and it runs when any currently running jobs finish. An upgrade typically takes only a few moments. This amount of time is long enough to download the latest version of the agent software (approximately 200 MB), unzip it, and restart the agent with the new version. You can monitor the status of your agents on the Agents tab.

We update the agent software with every Azure DevOps Server update. We indicate the agent version in the format {major}.{minor}. For instance, if the agent version is 2.1, then the major version is 2 and the minor version is 1.

When your Azure DevOps Server has a newer version of the agent, and that newer agent is only different in the minor version, it can usually be automatically upgraded. An upgrade is requested when a platform feature or one of the tasks that you use in the pipeline requires a newer version of the agent. Starting with Azure DevOps Server 2019, you don't have to wait for a new server release. You can upload a new version of the agent to your application tier, and that version is offered as an upgrade.

If you run the agent interactively, or if a newer major version of the agent is available, then you might have to manually upgrade the agents. You can easily upgrade the agent from the Agent pools tab under your project collection. Pipelines can't run without a compatible agent.

You can view the version of an agent. Go to Agent pools and select the Capabilities tab for the desired agent, as described in Configure agent capabilities.

To trigger agent update programmatically, you can use the Agent update API as described in the section How can I trigger agent updates programmatically for a specific agent pool?.

For servers with no internet access, manually copy the agent ZIP file to the following folder to use as a local file. Create the Agents folder if it isn't present:

  • Windows: %ProgramData%\Microsoft\Azure DevOps\Agents
  • Linux: usr/share/Microsoft/Azure DevOps/Agents
  • macOS: usr/share/Microsoft/Azure DevOps/Agents

Agent directory structure

When pipeline jobs run on agents, a directory structure is created to store the source code, binaries, and artifacts.

The agent's home directory is the directory where the agent is installed. The directory is typically located:

  • Microsoft-hosted agents: C:\agents\<agent version> on Windows, /Users/runner/runners/<agent version> on macOS, and /home/vsts/agents/<agent version> on Linux.
  • Self-hosted agents: C:\agent on Windows, Users/<username>/agent (~/agent) on macOS, and /home/vsts/agent on Linux.

The agent's work directory contains the workspace where the source and jobs output is stored. The work directory is typically located:

  • Microsoft-hosted agent: C:\a on Windows, /Users/runner/work on macOS, and/home/vsts/work on Linux.
  • Self-hosted agent: C:\agent\_work on Windows, ~/agent/work on macOS, and /home/agent/_work on Linux.

The work directory structure is:


    - /work directory
        - /1 build directory/pipeline workspace
            - /s source/working directory
            - /b binaries directory
            - /a artifacts staging directory
            - /TestResults Test results directory
Directory Description Examples Predefined variables
Agent home directory Where the agent is installed. Microsoft-hosted agent:
   Windows: C:\agents\3.248.0
   Linux: /home/vsts/agents/3.248.0
   macOS: /Users/runner/runners/3.248.0
Self-hosted agent:
   Windows: C:\agent
   Linux: home/agent
   macOS: ~/agent		 Agent.HomeDirectory
Work directory Where the agent stores the source code, binaries, and artifacts. Microsoft-hosted agent:
   Windows: C:\a
   Linux: /home/vsts/work
   macOS: /Users/runner/work
Self-hosted agent:
   Windows: C:\agent\_work
   Linux: /home/agent/_work
   macOS: ~/agent/work		 Agent.WorkFolder
Agent.RootDirectory
System.WorkFolder
Build directory or workspace Where the pipeline job runs. Microsoft-hosted agent:
   Windows: C:\a\1
   Linux: /home/vsts/work/1
   macOS: /Users/runner/work/1
Self-hosted agent:
   Windows: C:\agent\_work\1
   Linux: /home/agent/_work/1
   macOS: ~/agent/work/1		 Agent.BuildDirectory
Pipeline.Workspace
s - Source or working directory Contains the source code checked out from the repository. If there are multiple checkout steps in your job, your source code is checked out into directories named after the repositories as a subfolder of s. Microsoft-hosted agent:
   Windows: C:\a\1\s
   Linux: /home/vsts/work/1/s
   macOS: /Users/runner/work/1/s
Self-hosted agent:
   Windows: C:\agent\_work\1\s
   Linux: /home/agent/_work/1/s
   macOS: ~/agent/work/1/s		 Build.SourcesDirectory
Build.RepositoryLocalPath
System.DefaultWorkingDirectory
b - Binaries directory Contains the build outputs. Microsoft-hosted agent:
   Windows: C:\a\1\b
   Linux: /home/vsts/work/1/b
   macOS: /Users/runner/work/1/b
Self-hosted agent:
   Windows: C:\agent\_work\1\b
   Linux: /home/agent/_work/1/b
   macOS: ~/agent/work/1/b		 Build.BinariesDirectory
a - Artifacts staging directory Contains the build artifacts. Is cleaned between runs on self-hosted agents. Microsoft-hosted agent:
   Windows: C:\a\1\a
   Linux: /home/vsts/work/1/a
   macOS: /Users/runner/work/1/a
Self-hosted agent:
   Windows: C:\agent\_work\1\a
   Linux: /home/agent/_work/1/a
   macOS: ~/agent/work/1/a		 Build.StagingDirectory
Build.ArtifactStagingDirectory
System.ArtifactsDirectory
TestResults directory Contains the test results. Is cleaned between runs on self-hosted agents. Microsoft-hosted agent:
   Windows: C:\a\1\TestResults
   Linux: /home/vsts/work/1/TestResults
   macOS: /Users/runner/work/1/TestResults
Self-hosted agent:
   Windows: C:\agent\_work\1\TestResults
   Linux: /home/agent/_work/1/TestResults
   macOS: ~/agent/work/1/TestResults		 Common.TestResultsDirectory

On Microsoft-hosted agents, a different agent is used on each run, so the work directory isn't retained between runs. On self-hosted agents, only the artifacts staging directory and test results directories are cleaned between runs by default. For more information about the workspace clean option, see Workspace.

For more information about predefined variables, see Predefined variables.

FAQ

How do I make sure I have the latest agent version?

  1. Go to the Agent pools tab:

    1. Sign in to your organization (https://dev.azure.com/{yourorganization}).

    2. Select Azure DevOps > Organization settings.

      Screenshot that shows how to select Organization settings.

    3. Select Agent pools.

      Screenshot that shows how to select the Agent pools tab.

    1. Sign in to your project collection (http://your-server/DefaultCollection).

    2. Select Azure DevOps > Collection settings.

      Screenshot that shows how to select Collection settings.

    3. Select Agent pools.

      Select Agent pools.

    Screenshot that shows how to go to and select Agent pools.

  2. Select the pool that contains the agent.

  3. Make sure the agent is enabled.

  4. Go to the capabilities tab:

    1. From the Agent pools tab, select the desired agent pool.

      From Agent pools, select the desired agent pool.

    2. Select Agents and choose the desired agent.

      Select Agents and choose the agent.

    3. Choose the Capabilities tab.

      Choose the Capabilities tab.

      Note

      Microsoft-hosted agents don't display system capabilities. For a list of software installed on Microsoft-hosted agents, see Use a Microsoft-hosted agent.

    1. From the Agent pools tab, select the desired pool.

      Select the desired pool.

    2. Select Agents and choose the desired agent.

      Select Agents and choose the desired agent.

    3. Choose the Capabilities tab.

      Agent capabilities tab.

  5. Look for the Agent.Version capability. You can compare this value against the latest published agent version on the Azure Pipelines Agent page.

  6. Each agent automatically updates itself when it runs a task that requires a newer version of the agent. If you want to manually update some agents, right-click the pool, and then select Update all agents.

Can I update my agents that are part of an Azure DevOps Server pool?

Yes. Beginning with Azure DevOps Server 2019, you can configure your server to look for agent package files on a local disk. This configuration overrides the default version that came with the server at the time of its release. This scenario also applies when the server doesn't have access to the internet.

  1. From a computer with internet access, download the latest version of the agent package files (in .zip or .tar.gz form) from the Azure Pipelines Agent GitHub Releases page.

  2. Transfer the downloaded package files to each Azure DevOps Server Application Tier by using a method of your choice (for example, USB drive, network transfer, and so on). Place the agent files under the %ProgramData%\Microsoft\Azure DevOps\Agents folder. If there's no folder labeled Agents, create one.

  3. You're all set! Your Azure DevOps Server now uses the local files whenever the agents are updated. Each agent automatically updates itself when it runs a task that requires a newer version of the agent. But if you want to manually update some agents, right-click the pool, and then choose Update all agents.

Do self-hosted agents have any performance advantages over Microsoft-hosted agents?

In many cases, yes. If you use a self-hosted agent, you can run incremental builds. For example, if you define a pipeline that doesn't clean the repo and doesn't perform a clean build, your builds typically run faster. You don't get these benefits with a Microsoft-hosted agent unless you use features such as caching, because the agent is destroyed after the pipeline is completed.

A Microsoft-hosted agent can take longer to start your build. Although it often takes just a few seconds for your job to be assigned to a Microsoft-hosted agent, it can sometimes take several minutes for an agent to be allocated, depending on the load on our system.

Can I install multiple self-hosted agents on the same machine?

Yes. This approach might work well for agents that run jobs that don't consume many shared resources. For example, you could try it for agents that run releases that mostly orchestrate deployments and don't do much work on the agent itself.

You might find that in other cases you don't gain much efficiency by running multiple agents on the same machine. For example, it might not be worthwhile for agents that run builds that consume a lot of disk space and input/output resources.

You might also run into problems if parallel build jobs are using the same singleton tool deployment (for example, npm packages). One build might update a dependency while another build is using it, which could cause unreliable results and errors.

What do agents do when pipeline jobs are canceled?

For Microsoft-hosted agents, the agent is torn down and returned to the Azure Pipelines pool.

For self-hosted agents:

  • When a pipeline is canceled, the agent sends a sequence of commands to the process that's executing the current step.
  • The first command is sent with a timeout of 7.5 seconds.
  • If the process doesn't terminate, a second command is sent with a 2.5-second timeout.
  • If the process doesn't terminate, the agent commands it to be killed.
  • If the process ignores the two initial termination requests, it's forcibly killed.

The time from the initial request to termination is approximately 10 seconds.

The commands issued to the process to cancel the pipeline differ based on the agent operating system:

  • macOS and Linux: The commands sent are SIGINT, followed by SIGTERM, followed by SIGKILL.
  • Windows: The commands sent to the process are Ctrl+C, followed by Ctrl+Break, followed by Process.Kill.

How can I trigger agent updates programmatically for specific agent pool?

You can trigger agent updates for the pool by using the following API:

POST https://dev.azure.com/{organization}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0

POST https://{server url}/tfs/{collection}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0

Note

For more information, see API and Azure DevOps Server version mapping.

URI parameters

Name In Required Type Description
agentId query False string The agent to update. If it's not specified, an update is triggered for all agents.
organization path True string The name of the Azure DevOps organization.
poolId path True integer int32 The agent pool to use.
api-version query False string Version of the API to use. To use this version of the API, the value should be set to 6.0.

To trigger an agent update, the request body should be empty.

The Azure Pipelines agent is open source on GitHub.

Related content

For more information about agents, see the following modules from the Build applications with Azure DevOps learning path:

  • Last updated on