Setting up Service Principal auth

Service Principal (SP) authentication lets ADO Pilot review your pull requests using a Microsoft Entra identity instead of a Personal Access Token. There is no token to store, rotate, or leak — access is brokered by your Entra directory and you can revoke it at any time. SP auth is available on the Business plan and above. For a side-by-side comparison with PAT, see Choosing an auth method.

Why Service Principal

• No stored credential. ADO Pilot never holds a token — your Entra directory brokers every call.
• Central admin control. Revoke access any time from Entra. There is no PAT to rotate every 90 days.
• No token expiry. Reviews keep running; nothing to renew.

The one requirement: it must be your org's backing tenant

A service principal must live in the same Microsoft Entra tenant that backs your Azure DevOps organization. Unlike guest users, a service principal from another directory cannot be added to your org — so consent granted in the wrong tenant will not activate.

ADO Pilot determines your organization's backing tenant automatically from the organization name or URL you provide, so you don't need to look up a tenant ID. If you administer more than one Entra tenant, just make sure you grant consent while signed in as an admin of the directory that backs this organization.

If your organization is backed by personal Microsoft accounts (MSA) rather than Microsoft Entra, service-principal auth isn't available — connect with a Personal Access Token instead. See Creating a Personal Access Token.

Step 1 — Grant admin consent

A Microsoft Entra administrator grants ADO Pilot consent once. There are three ways to start, depending on who that admin is:

• You're the admin, signed in: open the Service Principal setup from your onboarding wizard or your dashboard and choose Grant admin consent. The consent link is pre-pinned to the correct directory.
• A different person is the admin (the common case): generate a shareable consent link from the same place and send it to them. The link opens the ADO Pilot connect page — they don't need an ADO Pilot account to use it, and it stays valid for 30 days.
• No link handy: an admin can open the connect page directly at app.adopilot.dev/connect. That page explains the benefits, offers a Sign in for guided setup option, and — for admins who'd rather not sign in — a generic Grant admin consent option using the standard Microsoft organizations flow.

Granting consent creates the ADO Pilot Code Reviewer service principal in your Entra tenant. It does not by itself give ADO Pilot access to your org — that's the next step.

Step 2 — Add the service principal to your Azure DevOps org

This step is always required, regardless of how consent was granted. You can do it two ways — pick whichever you prefer:

• Run a script (fastest). In your onboarding wizard, your dashboard — or, if you're the Entra admin who opened a shared consent link, right on the connect page once you've granted consent — the Service Principal step shows a pre-filled PowerShell script that does everything below in one run — set the org, add the service principal with Basic access and Contributors, and grant service-hook access. It uses the Azure CLI under your own interactive az login; no credential is embedded, and every value (your org, tenant, and the service principal's object id) is already filled in. Run it once as a Project Collection Administrator.
• Do it manually in the portal. Follow the numbered steps below.

Whichever you choose, ADO Pilot detects the result automatically within about five minutes and finishes activation. If you'd rather not wait, click I've done it — check now on the Service Principal step — it runs the check immediately and tells you right away whether the service principal is set up correctly, or exactly what's still missing. A passing check confirms your setup; activation then finishes on its own within a few minutes.

Manual steps

1. In Azure DevOps, open Organization settings → Users → Add users.
2. Add the ADO Pilot Code Reviewer service principal with Basic access.
3. Give it Contributors on the project(s) you want reviewed — this covers reading code and posting PR comments/status checks.
4. Grant it permission to manage service hooks for that project — see the callout below for the recommended command.

ADO Pilot detects the service principal automatically — usually within a few minutes — verifies it end to end, and finishes activation.

Microsoft references:

• Use service principals & managed identities in Azure DevOps
• Add users or groups to an organization
• Microsoft Entra access FAQ
• Manage Conditional Access policies
• Integrate with Service Hooks — required permissions
• Manage permissions with a command line tool

Already granted consent another way?

If your admin granted consent out of band — through the generic organizations flow, the Azure portal, or before you started setup — that's fine. Activation depends on the service principal being reachable, not on which page consent came from. To finish:

1. Make sure the service principal has been added to your org (Step 2 above).
2. Sign in and open Service Principal setup on your dashboard.
3. Choose "I've already granted consent."

ADO Pilot resolves your org's backing tenant, verifies the service principal, and activates — no need to re-run consent.

Troubleshooting

• A red "Fix organization name" warning during signup. ADO Pilot couldn't verify the organization name or URL you entered against Azure DevOps. Your account is still created, but the org connection can't finish — and activation will never complete — until the name is right. Click Fix organization name →, correct the value (it's the <org> in https://dev.azure.com/<org>), and resubmit. If you're confident the name is correct, this can also reflect a brief Azure DevOps outage — that variant of the message clears itself once verification succeeds.
• Consent granted in the wrong Entra directory. You signed in to the wrong tenant — re-grant consent while signed in as an admin of the directory that backs this organization.
• Stuck waiting after consent. Confirm Step 2 — the service principal must be added to the org with Basic access, Contributors, and the project-scoped Service Hooks Edit/View Subscriptions grant or Project Administrator (see the callout above). Contributors alone is not enough to create the service hook subscription reviews depend on. ADO Pilot re-checks on a short interval. You don't have to keep waiting — click I've done it — check now on the Service Principal step (or Re-check on your dashboard's Integration page) to probe immediately and surface the exact blocking permission if one is still missing. If you saw the "Fix organization name" warning during signup and dismissed it, start there first — a stuck activation is often just an unresolved org name, not a permissions issue.
• The consent link says it's invalid or expired. Links last 30 days, or until a newer one is generated. Sign in and generate a fresh link.
• Dashboard shows a specific service-hook permission error, or reviews never started at all. See Reviews never started: service-hook permission error for the per-project banner, what it means, and how to fix it.