azure-devops azure-devops-self-hosted-agent

What does --runAsAutoLogon do when configuring an Azure Devops Windows self-hosted agent?

At work I was asked a way to have a Windows self-hosted agent of Azure Devops start at system startup, not after the user login.

Looking at the docs I saw the --runAsAutoLogon option and tried it, providing the username and password. This didn't work. If I boot the system and wait on the windows lock screen, the agent doesn't come online (I check on the webapp). When I login, the service starts working.

The exact command I used to config the agent is:

.\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>'

Forgive my ignorance on the matter but am I doing something wrong or the option --runAsAutoLogon doesn't work the way I think it does?

EDIT: I corrected the flag name

EDIT: I added the command I used to configure it, and removed the last part about Services which wasn't relevant.

Solution

The option '--runAsAutoLogon' can be used when configuring a self-hosted Windows agent to run as interactive mode (Run interactively).

When an interactive mode self-hosted agent is needed?

When running a Azure DevOps pipeline, if certain pipeline steps need users to manually do some interactive actions, generally an interactive mode self-hosted agent is needed.

For example, during running some command lines in a pipeline job, one command line needs you manually enter the values of particular arguments to continue the subsequent processes, at this time, you need to use an interactive mode self-hosted agent to run this pipeline job.

Another common use case is running some certain tests from pipeline, the tests will start the UI windows (or web pages) of applications to ask users to take some actions by manual.

How to work with an interactive mode self-hosted agent?

If you configure an interactive mode self-hosted Windows agent without '--runAsAutoLogon' option, every time when using this agent, you need to:
- Manually logon the agent machine.
- Go to the installation directory of the agent and open a command prompt in this directory.
- Manually run the following command on the command prompt to start the agent.
```
.\run.cmd
```
- Keep the command prompt open, and also keep the machine online and screen unlocked.
If you configure the interactive mode self-hosted Windows agent with '--runAsAutoLogon' option, every time when using this agent, you need to:
- Manually logon the agent machine.
- Once you successfully logon the machine, due to the '--runAsAutoLogon' option, it will automatically open a command prompt from the agent installation directory and automatically run the command to start the agent.
- Keep the command prompt open, and also keep the machine online and screen unlocked.

So, the '--runAsAutoLogon' option mainly is helping you automatically start the agent once you successfully logon the the agent machine by manual. You must keep the machine online and screen unlocked during the agent is working.

For your case, if you pipelines do not need to run some interactive steps, you can configure the agent to run as service mode (Run as a service).

After successfully configuring a service mode agent, every time when using this agent, you just need to ensure the agent machine is online, and you do not need to manually logon the machine. Once the agent machine is online, the agent service will automatically start and keep online.

EDIT:

Below I will use an example to share you with the detailed steps to configure a self-hosted Windows agent to run as service:

Manually logon the Windows machine you want to set up self-hosted agent. Here I'm using a Windows VM, and I logon it via a RDP file or Remote Desktop Connection.
Download the latest available installation package of agent, and then unzip the package into a specified installation directory.
Go to the installation directory and open PowerShell as Administrator in the directory.
Execute the command ".\config.cmd" to start the configuration of the new agent. Provide the required information following the prompts step by step.
Once the agent is configurated successfully, can see the corresponding agent service from the system Services window of the Windows machine.
Keep the Windows machine online, and then logout from the machine via closing the remote connection. On another machine, sign in the Azure DevOps organization and go to the agent pool, can see the agent also is online.