Self-hosted Windows agents (2.x)
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Important
This article provides guidance for using the 2.x version agent software with Azure DevOps Server. If you're using Azure DevOps Services, see Self-hosted Windows agents.
To build and deploy Windows, Azure, and other Visual Studio solutions you need at least one Windows agent. Windows agents can also build Java and Android apps.
Before you begin:
- If your code is in Azure Pipelines and a Microsoft-hosted agent meets your needs, you can skip setting up a self-hosted Windows agent.
- Otherwise, you've come to the right place to set up an agent on Windows. Continue to the next section.
Learn about agents
If you already know what an agent is and how it works, feel free to jump right in to the following sections. But if you'd like some more background about what they do and how they work, see Azure Pipelines agents.
Check prerequisites
Make sure your machine has these prerequisites:
- Windows 7 SP1 ESU, 8.1, 10, or 11 (if using a client OS)
- Windows 2012 or higher (if using a server OS)
- PowerShell 3.0 or higher
- .NET Framework 4.6.2 or higher
Important
Starting December 2019, the minimum required .NET version for build agents is 4.6.2 or higher.
Recommended:
- Visual Studio build tools (2015 or higher)
If you're building from a Subversion repo, you must install the Subversion client on the machine.
You should run agent setup manually the first time. After you get a feel for how agents work, or if you want to automate setting up many agents, consider using unattended config.
Hardware specs
The hardware specs for your agents vary with your needs, team size, etc. It's not possible to make a general recommendation that applies to everyone. As a point of reference, the Azure DevOps team builds the hosted agents code using pipelines that utilize hosted agents. On the other hand, the bulk of the Azure DevOps code is built by 24-core server class machines running 4 self-hosted agents apiece.
Prepare permissions
Information security for self-hosted agents
The user configuring the agent needs pool admin permissions, but the user running the agent does not.
The folders controlled by the agent should be restricted to as few users as possible and they contain secrets that could be decrypted or exfiltrated.
The Azure Pipelines agent is a software product designed to execute code it downloads from external sources. It inherently could be a target for Remote Code Execution (RCE) attacks.
Therefore, it is important to consider the threat model surrounding each individual usage of Pipelines Agents to perform work, and decide what are the minimum permissions could be granted to the user running the agent, to the machine where the agent runs, to the users who have write access to the Pipeline definition, the git repos where the yaml is stored, or the group of users who control access to the pool for new pipelines.
It is a best practice to have the identity running the agent be different from the identity with permissions to connect the agent to the pool. The user generating the credentials (and other agent-related files) is different than the user that needs to read them. Therefore, it is safer to carefully consider access granted to the agent machine itself, and the agent folders which contain sensitive files, such as logs and artifacts.
It makes sense to grant access to the agent folder only for DevOps administrators and the user identity running the agent process. Administrators may need to investigate the file system to understand build failures or get log files to be able to report Azure DevOps failures.
Decide which user you'll use
As a one-time step, you must register the agent. Someone with permission to administer the agent queue must complete these steps. The agent will not use this person's credentials in everyday operation, but they're required to complete registration. Learn more about how agents communicate.
Authenticate with a personal access token (PAT)
- Sign in with the user account you plan to use in your Azure DevOps Server web portal (
https://{your-server}/DefaultCollection/
).
- Sign in with the user account you plan to use in your Azure DevOps organization (
https://dev.azure.com/{Your_Organization}
).
From your home page, open your profile. Go to your security details.
Create a personal access token.
Note
If you are configuring a deployment group agent, or if you see an error when registering a VM environment resource, you must set the PAT scope to All accessible organizations.
From your home page, open your user settings, and then select Personal access tokens.
Create a personal access token.
For the scope select Agent Pools (read, manage) and make sure all the other boxes are cleared. If it's a deployment group agent, for the scope select Deployment group (read, manage) and make sure all the other boxes are cleared.
Select Show all scopes at the bottom of the Create a new personal access token window window to see the complete list of scopes.
Copy the token. You'll use this token when you configure the agent.
Confirm the user has permission
Make sure the user account that you're going to use has permission to register the agent.
Is the user an Azure DevOps organization owner or TFS or Azure DevOps Server administrator? Stop here, you have permission.
Otherwise:
Open a browser and navigate to the Agent pools tab for your Azure Pipelines organization or Azure DevOps Server or TFS server:
Sign in to your organization (
https://dev.azure.com/{yourorganization}
).Choose Azure DevOps, Organization settings.
Choose Agent pools.
Sign in to your project collection (
http://your-server/DefaultCollection
).Choose Azure DevOps, Collection settings.
Choose Agent pools.
Choose Azure DevOps, Collection settings.
Choose Agent pools.
Select the pool on the right side of the page and then click Security.
If the user account you're going to use is not shown, then get an administrator to add it. The administrator can be an agent pool administrator, an Azure DevOps organization owner, or a TFS or Azure DevOps Server administrator.
If it's a deployment group agent, the administrator can be a deployment group administrator, an Azure DevOps organization owner, or a TFS or Azure DevOps Server administrator.
You can add a user to the deployment group administrator role in the Security tab on the Deployment Groups page in Azure Pipelines.
Note
If you see a message like this: Sorry, we couldn't add the identity. Please try a different identity., you probably followed the above steps for an organization owner or TFS or Azure DevOps Server administrator. You don't need to do anything; you already have permission to administer the agent queue.
Download and configure the agent
Azure Pipelines
Log on to the machine using the account for which you've prepared permissions as explained in the previous section.
In your web browser, sign in to Azure Pipelines, and navigate to the Agent pools tab:
Sign in to your organization (
https://dev.azure.com/{yourorganization}
).Choose Azure DevOps, Organization settings.
Choose Agent pools.
Sign in to your project collection (
http://your-server/DefaultCollection
).Choose Azure DevOps, Collection settings.
Choose Agent pools.
Choose Azure DevOps, Collection settings.
Choose Agent pools.
Select the Default pool, select the Agents tab, and choose New agent.
On the Get the agent dialog box, choose Windows.
On the left pane, select the processor architecture of the installed Windows OS version on your machine. The x64 version is intended for 64-bit Windows, whereas the x86 version is intended for 32-bit Windows. If you aren't sure which version of Windows is installed, follow these instructions to find out.
On the right pane, click the Download button.
Follow the instructions on the page to download the agent.
Unpack the agent into the directory of your choice. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces. A recommended folder is
C:\agents
. Extracting in the download folder or other user folders may cause permission issues. Then runconfig.cmd
, and respond to a series of questions to configure the agent.
Azure DevOps Server 2019 and Azure DevOps Server 2020
Log on to the machine using the account for which you've prepared permissions as explained above.
In your web browser, sign in to Azure DevOps Server 2019, and navigate to the Agent pools tab:
Sign in to your organization (
https://dev.azure.com/{yourorganization}
).Choose Azure DevOps, Organization settings.
Choose Agent pools.
Sign in to your project collection (
http://your-server/DefaultCollection
).Choose Azure DevOps, Collection settings.
Choose Agent pools.
Choose Azure DevOps, Collection settings.
Choose Agent pools.
Click Download agent.
On the Get agent dialog box, click Windows.
On the left pane, select the processor architecture of the installed Windows OS version on your machine. The x64 version is intended for 64-bit Windows, whereas the x86 version is intended for 32-bit Windows. If you aren't sure which version of Windows is installed, follow these instructions to find out.
On the right pane, click the Download button.
Follow the instructions on the page to download the agent.
Unpack the agent into the directory of your choice. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces. A recommended folder is
C:\agents
. Extracting in the download folder or other user folders may cause permission issues. Then runconfig.cmd
. This will ask you a series of questions to configure the agent.
Important
We strongly recommend you configure the agent from an elevated PowerShell window. If you want to configure as a service, this is required.
You must not use Windows PowerShell ISE to configure the agent.
Important
For security reasons we strongly recommend making sure the agents folder (C:\agents
) is only editable by admins.
Note
Please avoid using mintty based shells, such as git-bash, for agent configuration. Mintty is not fully compatible with native Input/Output Windows API (here is some info about it) and we couldn't guarantee correct work of setup script in this case.
Server URL and authentication
When setup asks for your server URL, for Azure DevOps Services, answer https://dev.azure.com/{your-organization}
.
When setup asks for your server URL, for TFS, answer https://{your_server}/tfs
.
When setup asks for your authentication type, choose PAT. Then paste the PAT token you created into the command prompt window.
Note
When using PAT as the authentication method, the PAT token is only used during the initial configuration of the agent. Later, if the PAT expires or needs to be renewed, no further changes are required by the agent.
Important
Make sure your server is configured to support the authentication method you want to use.
When you configure your agent to connect to Azure DevOps Server, you've got the following options:
Alternate Connect to Azure DevOps Server using Basic authentication. After you select Alternate you're prompted for your credentials.
Negotiate Connect to Azure DevOps Server as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate you're prompted for credentials.
Integrated (Default) Connect a Windows agent to Azure DevOps Server using the credentials of the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. You won't be prompted for credentials after you choose this method.
PAT After you choose PAT, paste the PAT token you created into the command prompt window. Use a personal access token (PAT) if your Azure DevOps Server instance and the agent machine are not in a trusted domain. PAT authentication is handled by your Azure DevOps Server instance instead of the domain controller.
Note
When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent. If the PAT needs to be regenerated, no further changes are needed to the agent.
Learn more at Communication with Azure Pipelines or Azure DevOps Server.
Choose interactive or service mode
For guidance on whether to run the agent in interactive mode or as a service, see Agents: Interactive vs. service.
If you choose to run as a service (which we recommend), the username you run as should be 20 characters or fewer.
Run the agent
Run interactively
If you configured the agent to run interactively, to run it:
.\run.cmd
To restart the agent, press Ctrl+C to stop the agent and then run run.cmd
to restart it.
Run once
For agents configured to run interactively, you can choose to have the agent accept only one job. To run in this configuration:
.\run.cmd --once
Agents in this mode will accept only one job and then spin down gracefully (useful for running in Docker on a service like Azure Container Instances).
Run as a service
If you configured the agent to run as a service, it starts automatically. You can view and control the agent running status from the services snap-in. Run services.msc
and look for one of:
Azure Pipelines Agent (*name of your agent*)
VSTS Agent (*name of your agent*)
vstsagent.(*organization name*).(*name of your agent*)
Note
To allow more flexibility with access control of an agent running as a service it
is possible to set up the agent service SID type as [SERVICE_SID_TYPE_UNRESTRICTED
] via
flag or prompt during interactive configuration flow.
By default, the agent service is configured with SERVICE_SID_TYPE_NONE
.
For more details about SID types please check this documentation.
To restart the agent, right-click the entry and choose Restart.
Note
If you need to change the agent's logon account, don't do it from the Services snap-in. Instead, see the information below to re-configure the agent.
To use your agent, run a job using the agent's pool. If you didn't choose a different pool, your agent will be in the Default pool.
Replace an agent
To replace an agent, follow the Download and configure the agent steps again.
When you configure an agent using the same name as an agent that already exists,
you're asked if you want to replace the existing agent. If you answer Y
,
then make sure you remove the agent (see below) that you're replacing. Otherwise,
after a few minutes of conflicts, one of the agents will shut down.
Remove and re-configure an agent
To remove the agent:
.\config remove
After you've removed the agent, you can configure it again.
Unattended config
The agent can be set up from a script with no human intervention.
You must pass --unattended
and then answers to all questions.
To configure an agent, it must know the URL to your organization or collection and credentials of someone authorized to set up agents.
All other responses are optional.
Any command-line parameter can be specified using an environment variable instead:
put its name in upper case and prepend VSTS_AGENT_INPUT_
.
For example, VSTS_AGENT_INPUT_PASSWORD
instead of specifying --password
.
Required options
--unattended
- agent setup will not prompt for information, and all settings must be provided on the command line--url <url>
- URL of the server. For example: https://dev.azure.com/myorganization or http://my-azure-devops-server:8080/tfs--auth <type>
- authentication type. Valid values are:pat
(Personal access token) - PAT is the only scheme that works with Azure DevOps Services.negotiate
(Kerberos or NTLM)alt
(Basic authentication)integrated
(Windows default credentials)
Authentication options
- If you chose
--auth pat
:--token <token>
- specifies your personal access token- PAT is the only scheme that works with Azure DevOps Services.
- If you chose
--auth negotiate
or--auth alt
:--userName <userName>
- specifies a Windows username in the formatdomain\userName
oruserName@domain.com
--password <password>
- specifies a password
Pool and agent names
--pool <pool>
- pool name for the agent to join--agent <agent>
- agent name--replace
- replace the agent in a pool. If another agent is listening by the same name, it will start failing with a conflict
Agent setup
--work <workDirectory>
- work directory where job data is stored. Defaults to_work
under the root of the agent directory. The work directory is owned by a given agent and should not be shared between multiple agents.--acceptTeeEula
- accept the Team Explorer Everywhere End User License Agreement (macOS and Linux only)--disableloguploads
- don't stream or send console log output to the server. Instead, you may retrieve them from the agent host's filesystem after the job completes.
Windows-only startup
--runAsService
- configure the agent to run as a Windows service (requires administrator permission)--runAsAutoLogon
- configure auto-logon and run the agent on startup (requires administrator permission)--windowsLogonAccount <account>
- used with--runAsService
or--runAsAutoLogon
to specify the Windows user name in the formatdomain\userName
oruserName@domain.com
--windowsLogonPassword <password>
- used with--runAsService
or--runAsAutoLogon
to specify Windows logon password (not required for Group Managed Service Accounts and Windows built in accounts such as 'NT AUTHORITY\NETWORK SERVICE')--enableservicesidtypeunrestricted
- used with--runAsService
to configure the agent with service SID type asSERVICE_SID_TYPE_UNRESTRICTED
(requires administrator permission)--overwriteAutoLogon
- used with--runAsAutoLogon
to overwrite the existing auto logon on the machine--noRestart
- used with--runAsAutoLogon
to stop the host from restarting after agent configuration completes
Troubleshooting configuring the agent with the runAsAutoLogon
option
Configuring the agent with the runAsAutoLogon
option runs the agent each time after restarting the machine.
Perform next steps if the agent is not run after restarting the machine.
If the agent was already configured on the machine
Before reconfiguring the agent, it is necessary to remove the old agent configuration, so try to run this command from the agent folder:
.\config.cmd remove --auth 'PAT' --token '<token>'
Check if the agent was removed from your agent pool after executing the command:
<Azure DevOps organization> / <Project> / Settings / Agent pools / <Agent Pool> / Agents
Remove the agent from your agent pool manually if it was not removed by running the command.
Then try to reconfigure the agent by running this command from the agent folder:
.\config.cmd --unattended --agent '<agent-name>' --pool '<agent-pool-name>' --url '<azure-dev-ops-organization-url>' --auth 'PAT' --token '<token>' --runAsAutoLogon --windowsLogonAccount '<domain\user-name>' --windowsLogonPassword '<windows-password>'
Specify the agent name (any specific unique name) and check if this agent appeared in your agent pool after reconfiguring.
It will be much better to unpack an agent archive (which can be downloaded here) and run this command from the new unpacked agent folder.
Check if the Windows registry key is recorded and saved correctly
Run the whoami /user
command to get the <sid>
. Open Registry Editor
and follow the path:
Computer\HKEY_USERS\<sid>\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
Check if there is the VSTSAgent
key. Delete this key if it exists, then close Registry Editor
and configure the agent by running the .\config.cmd
command (without args) from the agent folder. Before answering the question Enter Restart the machine at a later time?
, open Registry Editor
again and check if the VSTSAgent
key has appeared. Press Enter
to answer the question, and check if the VSTSAgent
key remains in its place after restarting the machine.
Check if Windows registry keys work fine on your machine
Create a autorun.cmd
file that contains the following line: echo "Hello from AutoRun!"
.
Open Registry Editor
and create in the path above a new key-value pair with the key AutoRun
and the value
C:\windows\system32\cmd.exe /D /S /C start "AutoRun" "D:\path\to\autorun.cmd"
Restart your machine. You have an issue with Windows registry keys if you do not see a console window with the Hello from AutoRun!
message.
Deployment group only
--deploymentGroup
- configure the agent as a deployment group agent--deploymentGroupName <name>
- used with--deploymentGroup
to specify the deployment group for the agent to join--projectName <name>
- used with--deploymentGroup
to set the project name--addDeploymentGroupTags
- used with--deploymentGroup
to indicate that deployment group tags should be added--deploymentGroupTags <tags>
- used with--addDeploymentGroupTags
to specify the comma separated list of tags for the deployment group agent - for example "web, db"
Environments only
--addvirtualmachineresourcetags
- used to indicate that environment resource tags should be added--virtualmachineresourcetags <tags>
- used with--addvirtualmachineresourcetags
to specify the comma separated list of tags for the environment resource agent - for example "web, db"
.\config --help
always lists the latest required and optional responses.
Diagnostics
If you're having trouble with your self-hosted agent, you can try running diagnostics. After configuring the agent:
.\run --diagnostics
This will run through a diagnostic suite that may help you troubleshoot the problem. The diagnostics feature is available starting with version 2.165.0.
Help on other options
To learn about other options:
.\config --help
The help provides information on authentication alternatives and unattended configuration.
Capabilities
Your agent's capabilities are cataloged and advertised in the pool so that only the builds and releases it can handle are assigned to it. See Build and release agent capabilities.
In many cases, after you deploy an agent, you'll need to install software or utilities. Generally you should install on your agents whatever software and tools you use on your development machine.
For example, if your build includes the npm task, then the build won't run unless there's a build agent in the pool that has npm installed.
Important
Capabilities include all environment variables and the values that are set when the agent runs. If any of these values change while the agent is running, the agent must be restarted to pick up the new values. After you install new software on an agent, you must restart the agent for the new capability to show up in the pool, so that the build can run.
If you want to exclude environment variables as capabilities, you can designate them by setting an environment variable VSO_AGENT_IGNORE
with a comma-delimited list of variables to ignore.
FAQ
How do I make sure I have the latest agent version?
Navigate to the Agent pools tab:
Sign in to your organization (
https://dev.azure.com/{yourorganization}
).Choose Azure DevOps, Organization settings.
Choose Agent pools.
Sign in to your project collection (
http://your-server/DefaultCollection
).Choose Azure DevOps, Collection settings.
Choose Agent pools.
Choose Azure DevOps, Collection settings.
Choose Agent pools.
Click the pool that contains the agent.
Make sure the agent is enabled.
Navigate to the capabilities tab:
From the Agent pools tab, select the desired agent pool.
Select Agents and choose the desired agent.
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.
From the Agent pools tab, select the desired pool.
Select Agents and choose the desired agent.
Choose the Capabilities tab.
From the Agent pools tab, select the desired pool.
Select Agents and choose the desired agent.
Choose the Capabilities tab.
Look for the
Agent.Version
capability. You can check this value against the latest published agent version. See Azure Pipelines Agent and check the page for the highest version number listed.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 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 the agent package files on a local disk. This configuration will override 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.
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.
Transfer the downloaded package files to each Azure DevOps Server Application Tier by using a method of your choice (such as USB drive, Network transfer, and so on). Place the agent files under the following folder:
- Windows:
%ProgramData%\Microsoft\Azure DevOps\Agents
- Linux:
usr/share/Microsoft/Azure DevOps/Agents
- macOS:
usr/share/Microsoft/Azure DevOps/Agents
Create the Agents folder if it is not present.
- You're all set! Your Azure DevOps Server will now use 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.
How do I make sure I have the latest v2 agent version?
Navigate to the Agent pools tab:
Sign in to your organization (
https://dev.azure.com/{yourorganization}
).Choose Azure DevOps, Organization settings.
Choose Agent pools.
Sign in to your project collection (
http://your-server/DefaultCollection
).Choose Azure DevOps, Collection settings.
Choose Agent pools.
Choose Azure DevOps, Collection settings.
Choose Agent pools.
Click the pool that contains the agent.
Make sure the agent is enabled.
Navigate to the capabilities tab:
From the Agent pools tab, select the desired agent pool.
Select Agents and choose the desired agent.
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.
From the Agent pools tab, select the desired pool.
Select Agents and choose the desired agent.
Choose the Capabilities tab.
From the Agent pools tab, select the desired pool.
Select Agents and choose the desired agent.
Choose the Capabilities tab.
Look for the
Agent.Version
capability. You can check this value against the latest published agent version. See Azure Pipelines Agent and check the page for the highest version number listed.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 select Update all agents.
Can I update my v2 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 the agent package files on a local disk. This configuration will override 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.
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.
Transfer the downloaded package files to each Azure DevOps Server Application Tier by using a method of your choice (such as USB drive, Network transfer, and so on). Place the agent files under the
%ProgramData%\Microsoft\Azure DevOps\Agents
folder. Create the Agents folder if it is not present.You're all set! Your Azure DevOps Server will now use 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.
I'm running a firewall and my code is in Azure Repos. What URLs does the agent need to communicate with?
If you're running an agent in a secure network behind a firewall, make sure the agent can initiate communication with the following URLs and IP addresses.
Domain URL | Description |
---|---|
https://{organization_name}.pkgs.visualstudio.com |
Azure DevOps Packaging API for organizations using the {organization_name}.visualstudio.com domain |
https://{organization_name}.visualstudio.com |
For organizations using the {organization_name}.visualstudio.com domain |
https://{organization_name}.vsblob.visualstudio.com |
Azure DevOps Telemetry for organizations using the {organization_name}.visualstudio.com domain |
https://{organization_name}.vsrm.visualstudio.com |
Release Management Services for organizations using the {organization_name}.visualstudio.com domain |
https://{organization_name}.vssps.visualstudio.com |
Azure DevOps Platform Services for organizations using the {organization_name}.visualstudio.com domain |
https://{organization_name}.vstmr.visualstudio.com |
Azure DevOps Test Management Services for organizations using the {organization_name}.visualstudio.com domain |
https://*.blob.core.windows.net |
Azure Artifacts |
https://*.dev.azure.com |
For organizations using the dev.azure.com domain |
https://*.vsassets.io |
Azure Artifacts via CDN |
https://*.vsblob.visualstudio.com |
Azure DevOps Telemetry for organizations using the dev.azure.com domain |
https://*.vssps.visualstudio.com |
Azure DevOps Platform Services for organizations using the dev.azure.com domain |
https://*.vstmr.visualstudio.com |
Azure DevOps Test Management Services for organizations using the dev.azure.com domain |
https://app.vssps.visualstudio.com |
For organizations using the {organization_name}.visualstudio.com domain |
https://dev.azure.com |
For organizations using the dev.azure.com domain |
https://login.microsoftonline.com |
Microsoft Entra sign-in |
https://management.core.windows.net |
Azure Management API's |
https://vstsagentpackage.azureedge.net |
Agent package |
To ensure your organization works with any existing firewall or IP restrictions, ensure that dev.azure.com
and *dev.azure.com
are open and update your allow-listed IPs to include the following IP addresses, based on your IP version. If you're currently allow-listing the 13.107.6.183
and 13.107.9.183
IP addresses, leave them in place, as you don't need to remove them.
IPv4 ranges
13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
IPv6 ranges
2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
Note
For more information about allowed addresses, see Allowed address lists and network connections.
How do I run the agent with self-signed certificate?
Note
Running the agent with a self-signed certificate only applies to Azure DevOps Server.
Run the agent with self-signed certificate
How do I run the agent behind a web proxy?
Run the agent behind a web proxy
How do I restart the agent
If you're running the agent interactively, see the restart instructions in Run interactively. If you're running the agent as a service, restart the agent by following the steps in Run as a service.
How do I set different environment variables for each individual agent?
Create a .env
file under agent's root directory and put environment variables you want to set into the file as following format:
MyEnv0=MyEnvValue0
MyEnv1=MyEnvValue1
MyEnv2=MyEnvValue2
MyEnv3=MyEnvValue3
MyEnv4=MyEnvValue4
How do I configure the agent to bypass a web proxy and connect to Azure Pipelines?
If you want the agent to bypass your proxy and connect to Azure Pipelines directly, then you should configure your web proxy to enable the agent to access the following URLs.
For organizations using the *.visualstudio.com
domain:
https://login.microsoftonline.com
https://app.vssps.visualstudio.com
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com
For organizations using the dev.azure.com
domain:
https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://vssps.dev.azure.com
To ensure your organization works with any existing firewall or IP restrictions, ensure that dev.azure.com
and *dev.azure.com
are open and update your allow-listed IPs to include the following IP addresses, based on your IP version. If you're currently allow-listing the 13.107.6.183
and 13.107.9.183
IP addresses, leave them in place, as you don't need to remove them.
IPv4 ranges
13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
IPv6 ranges
2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
Note
This procedure enables the agent to bypass a web proxy. Your build pipeline and scripts must still handle bypassing your web proxy for each task and tool you run in your build.
For example, if you are using a NuGet task, you must configure your web proxy to support bypassing the URL for the server that hosts the NuGet feed you're using.
I'm using TFS and the URLs in the sections above don't work for me. Where can I get help?
I use TFS on-premises and I don't see some of these features. Why not?
Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.
What is enable SERVICE_SID_TYPE_UNRESTRICTED for agent service?
When configuring the agent software on Windows Server, you can specify the service security identifier from the following prompt.
Enter enable SERVICE_SID_TYPE_UNRESTRICTED for agent service (Y/N) (press enter for N)
Previous versions of the agent software set the service security identifier type to SERVICE_SID_TYPE_NONE
, which is the default value for the current agent versions. To configure the security service identifier type to SERVICE_SID_TYPE_UNRESTRICTED
, press Y
.
For more information, see SERVICE_SID_INFO structure and Security identifiers.