Skip to main content
For what differs between this platform and the others, see Platform Support.

​
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. For self-hosted installations, follow the Azure DevOps Server guide.

​
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 is silently ignored, and Gitar never responds to your commands or questions.In Azure DevOps, go to Organization Settings → Users → Add users and invite a new user, for example gitar-bot@yourcompany.com.
2

Grant Project Administrator role

The service account needs the Project Administrator role on each project you want Gitar to access. This role grants the “Edit subscriptions” permission used to create and delete webhooks, during setup, when adding projects later, and when disconnecting. Keep it 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
To give Gitar access to every project in the organization at once, add the service account to the Project Collection Administrators group instead: Organization Settings → Permissions → Project Collection Administrators.
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, for example 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 stops working when the PAT expires. Once that is detected, Gitar emails the organization’s admins and shows a notification in the dashboard. To rotate, create a new PAT with the same scopes and update it under Settings → Configuration → Connections → Azure DevOps → Update PAT.
4

Connect in Gitar

  1. In the Gitar dashboard, go to Settings → Configuration → Connections
  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 validates the token and sets up webhooks on the selected projects automatically.

​
Permissions

​
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 needs Build (Read) to receive pipeline events and read build logs for CI failure analysis. For CI retry, select Build (Read & execute) instead. Build (Read) does not allow Gitar to retry builds.

​
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, so it does not require the service account to be a Project Collection Administrator. It works with either onboarding option above, organization-level or per-project.

​
Optional: Work Items (Read)

With this scope, Gitar reads the work items linked to a pull request and uses them as extra review context, for example checking that a change satisfies the requirements in its linked work item. If you leave it out, Gitar still reviews pull requests normally, without linked work items. You can add it later by creating a new PAT with this scope and updating the token.

​
Project Administrator role

The Project Administrator role grants the “Edit subscriptions” permission, 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, while the pipeline event subscription also requires the Build PAT scope.

​
Limitations

​
An Azure DevOps organization connects to one Gitar organization

An Azure DevOps organization can only be connected to a single Gitar organization. Connecting one that is already claimed by another Gitar organization returns an error asking you to contact that organization’s admin to be added as a member. Creating a second Gitar organization is not a way around it. A Gitar organization can connect more than one Azure DevOps organization. Once connected, click Add another org next to Azure DevOps in Settings → Configuration → Connections to connect additional ones.

​
Service hooks are created per project

Gitar creates its service hooks on the projects you select, so a project created after you connect delivers no events at all until you add it.
Nothing announces a project Gitar cannot see, and pull requests in it are never reviewed. After creating a project, add it under Settings → Configuration → Connections → Azure DevOps → Add projects.

​
Token expiry is detected after the fact, not ahead of it

Nothing warns you as the expiry date approaches. Gitar finds out once a call to Azure DevOps fails, and reviews stop until the token is replaced. You do get told at that point, and not only inside the app. Gitar emails the organization’s admins, the dashboard carries a high-priority notification, and the integration panel shows an alert linking to Update PAT. To avoid the gap entirely, add a calendar reminder a few days ahead of the expiry date you set when creating the token.

​
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 → Configuration → Connections → Azure DevOps, click Update PAT, and paste a newly created PAT.
Only projects selected during setup are monitored. To add more projects, go to Settings → Configuration → Connections → 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 → Configuration → Connections → Azure DevOps. Entering the new organization name with your existing token is enough. You do not need to disconnect first.