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

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.

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:

• macOS agent
• Linux agent
• Windows agent
• Docker agent

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.

Parallel jobs

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

YAML

Classic

On the Tasks tab of the pipeline, add the demand to your agent job.

Name	Condition	Value
SpecialSoftware	Exists	n/a
Agent.OS	Equals	Linux

Configure agent capabilities

Azure Pipelines UI

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:

2. Go to the Capabilities tab:

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

Azure DevOps CLI

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

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.

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.

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.

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

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:

2. Select the pool that contains the agent.

3. Make sure the agent is enabled.

4. Go to the 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.

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.