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 four 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 (Read) scope at validation time. The other three scopes (Code Status, Pull Request Threads, Service Hooks) 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 missing-scope error — re-create the token with all four 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 four 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 four 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

1. Return to the ADO Pilot onboarding wizard at the Connect to Azure DevOps step.
2. Click Personal Access Token.
3. Paste the token into the Paste your PAT here field.
4. In the Pull Request URL field, paste a pull request URL from the org you want reviewed (the wizard uses this to discover your organization and to schedule a first review).
5. Click Connect & Continue.

If the token is valid and the wizard can read your projects, it advances to Step 3 of 5 — Your first review. The wizard validates Code (Read) at this step by listing your projects; missing-scope errors for the other three scopes (Code Status, Pull Request Threads, Service Hooks) surface when service hooks are provisioned in the next step.

What to do if validation fails

The wizard shows a specific error for each common failure:

• Your PAT is missing the "..." scope. The token does not have one of the required scopes. This error can appear at validation (for Code (Read)) or later when the wizard provisions service hooks (for Code Status, Pull Request Threads, or Service Hooks). Delete the token in Azure DevOps and create a new one with all four 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, contact support.

For more help, see PAT scope errors.