Creating a Personal Access Token

To connect ADO Pilot to your Azure DevOps organization, you create a personal access token (PAT) in Azure DevOps with three specific scopes and paste it into the onboarding wizard. This page walks through the exact clicks.

When you need a PAT

You create a new PAT in two situations:

• First-time onboarding. The wizard's Connect to Azure DevOps step asks for one.
• Rotation or replacement. Every 90 days, or any time the previous token is compromised, expired, or owned by someone who has left the organization. See Rotating your PAT.

Required scopes

ADO Pilot needs the following Azure DevOps personal access token (PAT) scopes. Pick exactly these — do not grant Full access.

ADO Pilot's onboarding wizard probes the Code scope at validation time. The Code Status and Pull Request Threads scopes are exercised when the wizard provisions service hook subscriptions and when ADO Pilot posts the first review. A PAT missing any of them will fail later in onboarding or at first review with a scope error — re-create the token with all three scopes selected if you see one.

Recommended settings

• Expiration: 90 days. Shorter is fine; longer is discouraged because Azure DevOps caps PATs at one year and rotating regularly limits the blast radius of a leak.
• Organization: the single Azure DevOps organization you want ADO Pilot to review. Do not pick All accessible organizations — ADO Pilot only needs access to one.
• Scopes: Custom defined, with the scopes listed above. Do not pick Full access.

Step-by-step

Step 1 — Open the personal access tokens page in Azure DevOps

In Azure DevOps, click your profile icon in the top-right corner and choose Personal access tokens. The direct URL is https://dev.azure.com/{your-org}/_usersSettings/tokens.

Step 2 — Create a new token

1. Click New Token.
2. Set Name to something recognizable, for example ADO Pilot PR Review.
3. Set Organization to the org you want reviewed.
4. Set Expiration (UTC) to 90 days from today.
5. Under Scopes, click Custom defined and check the scopes from Required PAT scopes above.
6. Click Create.

Step 3 — Copy the token immediately

Azure DevOps shows the token string exactly once. Click the Copy button next to it. If you close the dialog without copying, you have to delete the token and start over.

Step 4 — Paste it into the onboarding wizard

The wizard's Connect step has three numbered sub-steps. Work through them in order:

1. Return to the ADO Pilot onboarding wizard at the Connect to Azure DevOps step and click Personal Access Token.
2. Under Your first review (sub-step 1), choose one of the two options — this also establishes your organization so the next step can generate a direct link to your PAT settings:
   • Run my first review now — paste an open pull request URL into the Pull Request URL field.
   • Skip for now — type your organization name or URL into the Organization Name or URL field.
3. Review the required scopes in sub-step 2. Once an organization or PR URL is entered, a Create PAT link appears — click it to open your Azure DevOps token settings page directly at the right URL.
4. Paste the token into the Paste your token field (sub-step 3) — its placeholder reads Paste your PAT here until you do.
5. Click Connect & Continue.

If the token is valid and the wizard can read your projects, it advances to Step 3 of 5 — titled Your first review if you pasted a PR URL, or Configure repositories if you chose Skip for now. The wizard validates Code (Read) at this step by listing your projects; missing-scope errors for the other scopes (Code Status, Pull Request Threads) don't surface until ADO Pilot runs your first review and tries to post the status check and inline comments.

What to do if validation fails

The wizard shows the specific scope validation error returned by Azure DevOps for each common failure:

• Organization not found. If you chose Skip for now and typed an organization name, the wizard checks it exists at https://dev.azure.com/<org>. If it doesn't, you'll see a "couldn't find an Azure DevOps organization with that name" error and a persistent "Fix organization name →" banner. Correct the org slug (the segment right after dev.azure.com/ — not a project or repo name) and click Connect & Continue again. See org_not_found.
• Scope validation error. The token does not have one of the required scopes. This error can appear at validation (for Code) or later, when ADO Pilot runs your first review and tries to post the status check or inline comments (for Code Status or Pull Request Threads). Delete the token in Azure DevOps and create a new one with all required scopes checked — see Required PAT scopes.
• Invalid or expired PAT. The token string is wrong or the expiration date has already passed. Confirm in Azure DevOps that the token still exists and is not expired, then create a new one if needed.
• Internal error: discovery state missing. Please retry validation. A transient backend hiccup. Click Connect & Continue again. If it persists, open a support request.
• Dashboard shows a service-hook permission error (not a scope error). This is a different failure from the scope errors above: the token's scopes are fine, but the Azure DevOps user the token belongs to lacks the Project Administrator role (or the org-wide Edit/View Subscriptions grant on the Service Hooks namespace — a real tradeoff against Project Administrator, not simply narrower) needed to create the subscription that delivers pull-request events — an organization role, not a PAT scope. See Reviews never started: service-hook permission error.

For more help, see PAT scope errors.