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

# Azure DevOps

> Register a Microsoft Entra ID (Azure AD) application to enable Azure DevOps OAuth for your on-prem Garth Assist deployment.

<Info>
  This page covers **on-prem (self-hosted)** setup. You register your own Entra ID
  (Azure AD) app so Azure DevOps OAuth runs against your tenant. For the hosted
  SaaS integration, see [Setup → Azure DevOps](https://app.heygarth.ai/settings/integrations).
</Info>

<Warning>
  You need permission to create **App registrations** in your Microsoft Entra ID
  tenant and to **grant admin consent** for the requested API permissions.
</Warning>

<Note>
  Create the OAuth app in the **same Microsoft Entra ID tenant** that your Azure
  DevOps organization is connected to. An app registered in a different tenant
  cannot authenticate against that Azure DevOps organization.
</Note>

## Register the Garth Assist app

<Steps>
  <Step title="Open the Azure portal">
    Sign in to the [Azure portal](https://portal.azure.com/) and go to
    **Microsoft Entra ID → App registrations**.
  </Step>

  <Step title="Create a new registration">
    Click **New registration** and fill in the details below.

    | Field                       | Value                                                                                |
    | --------------------------- | ------------------------------------------------------------------------------------ |
    | **Name**                    | `Garth Assist`                                                                       |
    | **Supported account types** | Accounts in any organizational directory (**multitenant**)                           |
    | **Redirect URI**            | `https://<dns-host>/api/garth-assist/oauth/azuredevops/callback` (platform: **Web**) |

    Under **Supported account types**, select **Accounts in any organizational
    directory (Any Microsoft Entra ID tenant - Multitenant)** to enable multi-tenant
    support.

    <Tip>
      Replace `<dns-host>` with the DNS host of your on-prem Garth deployment —
      for example `https://app.heygarth.ai/api/garth-assist/oauth/azuredevops/callback`.
    </Tip>

    Click **Register**.
  </Step>

  <Step title="Create a client secret">
    Open **Certificates & secrets → Client secrets** and click
    **New client secret**. Set a description and expiry, then click **Add**.
    Copy the secret **Value** immediately.

    <Warning>
      The client secret value is shown only once. Copy and store it securely
      before leaving the page.
    </Warning>
  </Step>

  <Step title="Add API permissions">
    Open **API permissions → Add a permission** and add the delegated permissions
    below, then click **Grant admin consent** for your tenant.

    **Azure DevOps**

    | Permission        | Description             |
    | ----------------- | ----------------------- |
    | `vso.build`       | Build (read)            |
    | `vso.code_status` | Code (status)           |
    | `vso.code_write`  | Code (read and write)   |
    | `vso.profile`     | User profile (read)     |
    | `vso.project`     | Project and team (read) |

    **Microsoft Graph**

    | Permission       | Description                                         |
    | ---------------- | --------------------------------------------------- |
    | `email`          | View users' email address                           |
    | `offline_access` | Maintain access to data you have given it access to |
    | `openid`         | Sign users in                                       |
    | `profile`        | View users' basic profile                           |
    | `User.Read`      | Sign in and read user profile                       |

    <Info>
      All permissions are **Delegated**. After granting admin consent, each
      permission's **Status** should show a green **Granted for \<tenant>** check.
    </Info>
  </Step>
</Steps>

## Environment variables

Record the following values for your on-prem deployment:

| Environment variable         | Value                                                            |
| ---------------------------- | ---------------------------------------------------------------- |
| `AZURE_DEVOPS_CLIENT_ID`     | The **Application (client) ID** from the app's **Overview** page |
| `AZURE_DEVOPS_CLIENT_SECRET` | The **client secret** value created in step 3                    |