Azure DevOps build agent’s frustrating install mess

Sometimes I have to remind myself that I get paid pretty well to solve frustrating puzzles like this. “Go set up automated builds” they said. “It will save us lots of time” they said. I’ve done this before, so I had some idea what I was in-for, but unfortunately, I forgot all of the tricks and solutions. So I’m going to leave this here for future-me to find, instead of searching goog and bing and stackover, only to find nothing helpful.

Pre: My dev/QA/Stage servers are behind a firewall, on a private network but our ADO (Azure DevOps) server was in MS’s cloud. Our security folks would not allow a FW hole for ADO. So I figured I would install a local build-agent (old-skoo style) on my dev server and attach it to our ADO repo & stuff.

What I was trying to do should’ve been simple. I found a nice article with steps for installing a local build-agent for ADO (Azure DevOps). My AD admin made a “service account” for this. I hopped onto my server and checked outgoing firewall rules for https://dev.azure.com/[My department's site]/[my project]/. Good to go. Account works, pre-requisites are installed. I setup a build-agent-pool, download the build agent software and kick-off the installation. I’m feeling optimistic.

Five seconds into the install, pretty-much step 1, I run into a problem. I try to run config.cmd, and nada. It takes a bunch of time, but eventually I figure out that the correct syntax is actually this:

PS C:\dev\buildagent> .\config.cmd

For some reason, you must prefix with .\ or it doesn’t work. Whatever. Fine.
It gives me some old-school ascii graphic for Azure Pipelines agent v2.211.1. and asks for settings:

> Enter server URL > https://dev.azure.com/MyDepartment/MyProject/
> Enter authentication type (press enter for PAT) >
(... since I followed directions, and already got my token, I pressed enter)
> Enter personal access token > **********************************************
(... and I get this )
Error reported in diagnostic logs. Please examine the log for more details.
- c:\dev\buildagent\_diag\Agent_20221107-123456-utc.log
Page not found.
Failed to connect. Try again or ctrl-c to quit

Dang-it! At least it gave me a log file. I’m sure it will point out the problem, so I can quickly resolve it.

Hmm the log file has lots of noise in it. So ffw down to the line with ” ERR “:
[2022-11-07 21:54:10Z ERR LocationServer] Microsoft.VisualStudio.Services.WebApi.VssServiceResponseException: Page not found.

Horse-feathers! I have the browser window open. I can see the goshdarn page. Wait a sec. Two lines up, it tried to use another page/url.
[2022-11-07 21:54:10Z ERR VisualStudioServices] GET request to https://dev.azure.com/MyDepartment/MyProject/_apis/connectionData?connectOptions=1&lastChangeId=-1&lastChangeId64=-1

Okay. Let’s copy-paste that address. Weird. 404. So how do I resolve that? Call Microsoft? “Hello, could you please install your “_apis” stuff into my project’s folder on your server? Mkay, thanks.” Ha.

Problem: (Now I get it) The url cannot include the project (maybe this would make too-much sense or something). It has to be the url for my entire department instead.
Solution: Checking the department’s URL in a browser worked (see below). On to the next headache.

> Enter server URL > https://dev.azure.com/MyDepartment/
> Enter authentication type (press enter for PAT) >
(... since I followed directions, and already got my token, I pressed enter)
> Enter personal access token > ***********************************************
Connecting to server ...
VS30063: You are not authorized to access https://dev.azure.com.

So now what? What the heck is it talking about “not authorized”? I’m on-the-server right now, I have a browser window opened, pointed at that site, and clearly I do have access. The logs say…

[2022-11-07 15:54:08Z ERR LocationServer] Microsoft.VisualStudio.Services.Common.VssUnauthorizedException: VS30063: You are not authorized to access https://dev.azure.com.
at Microsoft.VisualStudio.Services.Common.VssHttpMessageHandler.SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
...
[2022-11-07 15:54:08Z ERR Terminal] WRITE ERROR (exception):
[2022-11-07 15:54:08Z ERR Terminal] Microsoft.VisualStudio.Services.Common.VssUnauthorizedException: VS30063: You are not authorized to access https://dev.azure.com.
...
[2022-11-07 15:54:08Z ERR Terminal] WRITE ERROR: Failed to connect. Try again or ctrl-c to quit

Problem: “WRITE ERROR”. This one was my fault. When I generated the token, it asked me which permissions I wanted to grant. I guess I was too careful. I didn’t think a bot account would need to write to our code repo. Seems a little risky/sketchy, but it isn’t giving me a lot of options right now.
Solution: I went back into the ADO web site (as my service account) and generated a new token with more permissions, and things worked. Okay, fine, but I’m keeping a close eye on ya!

Oh hey, that did it! I got it working. Only one entire day wasted on this. (hide-the-pain)

Lessons learned:
– Use the server URL for my department, not my project: https://dev.azure.com/MyDepartment/
– Start off by generating a token with ample/generous permissions and tighten it down later, after you get the first one working