Skip to main content
Azure DevOps support is currently in beta. For access or to leave feedback, please email us at: developers@gitar.ai

​
Overview

Gitar connects to repositories in Azure DevOps via a Personal Access Token (PAT) associated with a dedicated service account. Gitar uses this token to read pull requests, post review comments, and set up webhooks that deliver events to Gitar in real time.

​
Prerequisites

  • An Azure DevOps organization
  • Permission to create service accounts (users) in your Azure DevOps organization
  • Project Administrator role on the projects you want to connect

​
Setup Instructions

1

Create a dedicated service account

Create a new user in your Azure DevOps organization to act as the Gitar service account.A dedicated account is required, not optional. Gitar identifies its own comments by the account ID of the PAT owner and ignores them to avoid processing its own output. If you use a personal account, every comment you post on pull requests will be silently ignored — Gitar will treat them as its own and never respond to your commands or questions.In Azure DevOps, go to Organization Settings → Users → Add users and invite a new user (e.g., gitar-bot@yourcompany.com).
2

Grant Project Administrator role

The service account needs Project Administrator role on each project you want Gitar to access. This role is used to create and delete webhooks — during initial setup, when adding projects later, and when disconnecting. It must be kept for as long as the integration is active.For each project:
  1. Go to Project Settings → Permissions
  2. Select the Project Administrators group
  3. Add the Gitar service account as a member
If you want to give Gitar access to all projects in the organization, you can instead add the service account to the Project Collection Administrators group at the organization level: go to Organization Settings → Permissions → Project Collection Administrators and add the service account there.
3

Create a Personal Access Token

Sign in to Azure DevOps as the Gitar service account and create a PAT:
  1. Click your profile avatar in the top right → Personal access tokens
  2. Click New Token
  3. Set a name (e.g., Gitar) and choose your organization from the Organization dropdown
  4. Set an expiration date — note this date so you can rotate the token before it expires
  5. Select Custom defined under Scopes and enable the following:
  1. Click Create and copy the token — it will not be shown again
Gitar will stop working when the PAT expires. Gitar will notify you in the dashboard when expiry is detected. To rotate, create a new PAT with the same scopes and update it under Settings → Integrations → Azure DevOps → Update token.
4

Connect in Gitar

  1. In the Gitar dashboard, go to Settings → Integrations
  2. Click Connect next to Azure DevOps
  3. Enter your Azure DevOps organization name (the part after dev.azure.com/ in your URL)
  4. Paste the PAT
  5. Select the projects you want Gitar to access
  6. Click Connect
Gitar will validate the token and set up webhooks on the selected projects automatically.

​
Permissions Explained

​
Code (Read & write)

Gitar reads pull request metadata, diffs, and commit history to analyze changes. Write access is needed to post review comments, set reviewer votes, update PR descriptions, and report commit statuses.

​
Pull Request Threads (Read & write)

Gitar reads and writes to pull request comment threads. This scope is separate from general code access and is required for Gitar to post inline code review comments, reply to threads, and resolve discussions.

​
Build (Read)

Gitar subscribes to pipeline run-state-changed events as part of webhook setup. Azure DevOps requires the Build scope on the PAT for this specific subscription.

​
Graph & Identity (Read)

Gitar reads the organization’s member list so admins can assign Gitar seats to the right people from Settings → Billing. This scope is read-only and available to any organization member — it does not require the service account to be a Project Collection Administrator, so it works with both onboarding options above (organization-level or per-project).

​
Work Items (Read) — optional

This scope is optional. With it, Gitar reads the work items linked to a pull request and uses them as additional review context — for example, checking that a change satisfies the requirements described in its linked work item. If you leave it out, Gitar still reviews pull requests normally; it just won’t use linked work items for extra context. You can always add it later by creating a new PAT with this scope and updating the token.

​
Project Administrator role

The Project Administrator role grants the service account the “Edit subscriptions” permission, which is required to create and manage the service hook subscriptions Gitar uses to receive pull request events in real time. This is separate from the PAT scopes above: webhook creation for most event types is gated by this project role, but the pipeline event subscription additionally requires the Build PAT scope.

​
Troubleshooting

The service account does not have Project Administrator role on the project. Follow the step above to add the service account to the Project Administrators group for each connected project.
The PAT is missing the Build (Read) scope. Azure DevOps requires it to create the pipeline-events webhook, even when the service account already has Project Administrator role. Edit the PAT, add Build → Read, and re-validate. This is a PAT scope, not a project role. Adding the role alone will not fix it.
The PAT has likely expired. Go to Settings → Integrations → Azure DevOps, click Update token, and paste a newly created PAT.
Only projects selected during setup are monitored. To add more projects, go to Settings → Integrations → Azure DevOps → Add projects.
Nothing to do — Gitar repairs itself. It identifies your organization by an immutable ID rather than its name, so the next pull request event carries the new name and Gitar updates its records automatically.If you renamed the organization and reviews still fail after your next pull request activity, reconnect in Settings → Integrations → Azure DevOps. Entering the new organization name with your existing token is enough; you do not need to disconnect first.