> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps Server

> Connect your self-hosted Azure DevOps Server repositories to Gitar

<Note>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](mailto:developers@gitar.ai).</Note>

## 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)).

## 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](/connecting-code/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:

```
https://api.gitar.ai
```

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](#troubleshooting).

## Setup Instructions

<Steps>
  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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:

    | Scope                       | Permission   |
    | --------------------------- | ------------ |
    | **Code**                    | Read & write |
    | **Pull Request Threads**    | Read & write |
    | **Build**                   | Read         |
    | **Graph & Identity**        | Read         |
    | **Work Items** *(optional)* | Read         |

    5. Click **Create** and copy the token. It will not be shown again

    <Callout type="warn" title="Token expiry">
      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**.
    </Callout>
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion title="Validation fails to reach the server, or times out">
    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](/connecting-code/network-access).
  </Accordion>

  <Accordion title="Connected, but pull request events never arrive">
    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.
  </Accordion>

  <Accordion title="Validation fails with a 'Service Hooks permission' error">
    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.
  </Accordion>

  <Accordion title="Validation fails with a 'Build (Read) scope' error">
    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.
  </Accordion>

  <Accordion title="Gitar stops working after some time">
    The PAT has likely expired. Go to **Settings → Integrations → Azure DevOps**, click **Update token**, and paste a newly created PAT.
  </Accordion>

  <Accordion title="Gitar doesn't see my repositories after connecting">
    Only projects selected during setup are monitored. To add more projects, go to **Settings → Integrations → Azure DevOps → Add projects**.
  </Accordion>
</AccordionGroup>