Skip to main content
Azure DevOps Server (self-hosted) support is in early access and currently covers Azure DevOps Server 2022. To request access or share feedback, email developers@gitar.ai.

​
Overview

Gitar connects to a self-hosted Azure DevOps Server the same way it connects to Azure DevOps in the cloud: a Personal Access Token (PAT) on a dedicated service account, used to read pull requests, post review comments, and set up webhooks that deliver events to Gitar. The difference is the network. Your Server runs inside your own network, so two paths have to be open before you connect: Gitar has to reach your Server to read pull requests and manage webhooks, and your Server has to reach Gitar to deliver events. Set both up first, then follow the setup steps.

​
Prerequisites

  • Azure DevOps Server 2022.
  • Permission to create a user in your Server instance.
  • Project Administrator role on the projects you want to connect.
  • Network connectivity in both directions (see Network and connectivity).

​
Network and connectivity

This is the part that differs from the cloud. Because your Server is self-hosted, both paths below must be open.

​
Gitar to your Server (inbound)

Gitar calls your Server’s REST API and clones over HTTPS to read pull requests, post comments, and create webhooks. Your Server must be reachable from Gitar:
  • Reachable from the internet at a stable HTTPS URL, for example https://devops.yourcompany.com.
  • A valid, publicly trusted TLS certificate. Self-signed certificates are not supported.
  • If your Server enforces an IP allowlist, permit Gitar’s public IP addresses. See Network Access.

​
Your Server to Gitar (outbound webhooks)

Your Server delivers pull request events to Gitar through Azure DevOps service hooks. The Server makes an outbound HTTPS call to Gitar for each event, so allow egress from your Server to:
Port 443. If your Server reaches the internet through an outbound proxy, allow api.gitar.ai in the proxy configuration. No Azure DevOps Server setting needs to change: Server accepts external webhook subscriptions by default, so opening the egress path is all that is required. If pull request events never reach Gitar after connecting, this egress path is the usual cause, see Troubleshooting.

​
Setup Instructions

1

Create a dedicated service account

Create a dedicated account for Gitar in your Server’s identity source (Active Directory or the local accounts your Server uses), for example gitar-bot, and make sure it is a valid user in the collection you want to connect.A dedicated account is required, not optional. Gitar identifies its own comments by the account 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, and Gitar will never respond to your commands or questions.
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 collection at once, add the service account to the Project Collection Administrators group instead: Collection Settings (or Azure DevOps Server admin) → Security → Project Collection Administrators.
3

Create a Personal Access Token

Sign in to your Server’s web portal as the Gitar service account and create a PAT:
  1. Click your profile avatar in the top right → Security → Personal access tokens
  2. Click New Token
  3. Set a name (e.g., Gitar) and an expiration date. Note the date so you can rotate the token before it expires
  4. 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, and notifies you in the dashboard when it detects expiry.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. Check Connecting to Azure DevOps Server (on-premises)
  4. Server URL: your Server’s base URL, for example https://devops.yourcompany.com. Enter the host plus any virtual directory, but do not include the collection
  5. Azure DevOps Collection Name: the project collection, the first path segment after the server URL, commonly DefaultCollection
  6. Paste the PAT
  7. Select the projects you want Gitar to access
  8. Click Connect
Gitar validates the token, confirms it can reach your Server, and sets 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 collection’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 member, so it does not require the service account to be a Project Collection Administrator.

​
Work Items (Read), optional

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, it just will not use 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. 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.

​
Troubleshooting

Gitar could not reach your Server from the internet. Confirm the Server URL is correct and publicly reachable, the TLS certificate is valid and publicly trusted (self-signed is not supported), and, if you enforce an IP allowlist, that Gitar’s IPs are permitted. See Network Access.
Your Server cannot reach Gitar to deliver webhooks. Allow outbound HTTPS from the Server to https://api.gitar.ai on port 443, directly or through your outbound proxy. No Azure DevOps Server setting needs to change. This is a firewall or proxy rule.
The service account does not have the Project Administrator role on the project. Add it to the Project Administrators group for each connected project, or to Project Collection Administrators for the whole collection.
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.