Rotating or replacing your PAT
How to swap an Azure DevOps personal access token for ADO Pilot on a routine schedule or in response to a compromise.
Last updated
You replace the personal access token (PAT) ADO Pilot uses by minting a new one in Azure DevOps and pasting it into the Integration settings page in your dashboard. There are two times you do this: on a 90-day schedule, and immediately after any suspected compromise.
When to rotate
Scheduled rotation (every 90 days)
Azure DevOps PATs expire on a fixed date. We recommend a 90-day expiration window — short enough to limit blast radius, long enough that rotation is a quarterly task instead of a weekly one. Plan to rotate before the existing token expires; if it lapses, reviews stop firing until you replace it.
Emergency rotation (rotate now)
Rotate immediately if any of these happen:
- The token string was pasted somewhere it shouldn't be — chat, email, a screenshot, an unencrypted note, a public log.
- A laptop or password vault that held the token was lost or compromised.
- The user who created the token has left your organization or had their access revoked.
- You discover the existing token has scopes broader than the four ADO Pilot needs (for example, Full access).
- Your security team flags any incident that touches the workstation where the token was created.
When you rotate for an emergency, mint the new PAT first, save it in ADO Pilot, then revoke the old one in Azure DevOps. That sequence avoids a coverage gap.
Required scopes for the new token
The replacement PAT needs the same scopes as the original. There are no additional scopes for rotation:
ADO Pilot needs the following Azure DevOps personal access token (PAT) scopes. Pick exactly these — do not grant Full access.
| Scope | Permission level | Why ADO Pilot needs it |
|---|---|---|
| Code | Read | Read pull request diffs and file contents to feed the review pipeline. |
| Code (status) | Read & write | Post the adopilot/ai-pr-review status check that you can wire into branch policy. |
| Pull Request Threads | Read & write | Post inline review comments and reply to thread replies on the PR. |
| Service Hooks | Read & write | Create and manage the two webhook subscriptions that deliver PR events to ADO Pilot. |
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.
How to rotate
Step 1 — Create a new PAT in Azure DevOps
Follow Creating a Personal Access Token to mint a fresh token with all four scopes and a 90-day expiration. Copy the token string the moment Azure DevOps shows it — you only get one chance.
Step 2 — Open the Integration settings page
In the ADO Pilot dashboard, go to Settings then Integration. The Personal Access Token card shows the existing token's expiration date and remaining days.
Step 3 — Paste the new token
- Click Rotate PAT.
- In the dialog, paste the new token into the New PAT field.
- Click Save token.
The dialog notes that the old token will be invalidated immediately — that is, ADO Pilot starts using the new token for its next outbound call. The previous token continues to exist in Azure DevOps until you revoke it in Step 5.
Step 4 — Confirm the connection is healthy
The Integration page should now show:
- The expiration date reset to roughly 90 days from today.
- The connection status indicator green.
Push a small commit to a test branch and open a draft PR to confirm a review fires. If it does not, see PAT scope errors and Connection status shows "Unknown".
Step 5 — Revoke the old token in Azure DevOps
Go to User Settings → Personal access tokens in Azure DevOps, find the previous token by name, and click Revoke. Skipping this step is the most common rotation mistake — the old token remains valid until its original expiry date, which defeats the point of rotating after a compromise.
What stays the same after rotation
- Repository configuration (which repos are reviewed, exclusion patterns, severity thresholds).
- Service hook subscriptions in Azure DevOps. ADO Pilot does not re-create the subscriptions during a PAT rotation.
- Review history, comments, and status checks already posted on existing PRs.
- Your plan, billing, team membership, and review credit balance.
What changes
- The stored PAT credential, encrypted at rest in our backend.
- The expiration date displayed on the Integration page (resets to your new token's expiry).
- Outbound calls from ADO Pilot to Azure DevOps now sign with the new token.
Troubleshooting rotation
- Connection status shows "Unknown" after saving. The new token is missing a required scope or is otherwise invalid. See Connection status shows "Unknown" and re-check the four scopes against Required PAT scopes.
- Reviews stop firing after rotation. Rotation does not touch service hook subscriptions, so this usually means something else changed at the same time. See Webhook 401s and reviews stopped firing.
- You forgot to copy the new token before closing the Azure DevOps dialog. The token cannot be recovered. Revoke the half-created token in Azure DevOps and start over.