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

# Azure DevOps

> Connect your Azure DevOps repositories to Weave

Connect Azure DevOps to sync pull requests, commits, code reviews, team members, and Boards work items. Choose Azure DevOps Services (Microsoft-hosted OAuth) or Azure DevOps Server 2022 (HTTPS and PAT, REST 7.0). Compatibility on your exact Server update and deployment must be validated before rollout.

## What's synced

* Pull requests and their metadata
* Commits and code changes
* Code reviews and comments (threads and votes)
* Team members and organization structure
* Repository and project information
* Boards projects, teams, iterations, work items, status and estimate changes, and pull-request links
* CI/CD build pipelines and classic **Release Management** deployments for Services and Server (for [DORA deploy metrics](/metrics/ci-deploy-frequency)).

## Connecting Azure DevOps Server 2022

1. Use the complete public HTTPS collection URL, including its collection path. Publicly routable destinations require no operator allowlist. For private-network destinations, ask your Weave operator to approve the exact URL in `AZUREDEVOPS_SERVER_ALLOWED_COLLECTIONS` on every runtime.
2. Configure `EXTERNAL_KEY_ENCRYPTION_KEY`, the established Tink AEAD JSON keyset, on the backend, sync workers and every scheduled/on-demand clone runtime. The same key must be available to all consumers. Server PAT storage fails closed without it, including self-hosted deployments. Back up the key securely; losing it requires reconnecting with new PATs.
3. Verify those runtimes can resolve and reach the Server directly. Install corporate CA roots in both the Go/runtime and Git trust stores. TLS verification cannot be disabled, redirects are rejected, and HTTP proxies are not used for Server access. Explicitly approved private addresses are allowed; loopback, link-local and metadata addresses are always blocked. Git must support `http.curloptResolve` for DNS pinning.
4. Create a PAT for a service account with **Code (read)**, **Project and Team (read)** and **Identity (read)**, plus Reader access to the selected Git repositories. Add **Work Items (read)** to enable Boards sync. Identity (read) lets Weave read the collection-local Identities API (`{collection}/_apis/identities`) so PR authors, reviewers, commenters and commit contributors are mapped to Weave members by their directory email; connect and PAT rotation verify it after repository access, and a PAT without it fails validation. The PAT owner is only a credential: it is never treated as a contributor or an admin. Windows/NTLM/Kerberos and TFVC are not supported. Microsoft Entra/OAuth integration authentication is Services-only.
5. In **Data → Azure DevOps → Connect**, choose **Server**, enter the collection URL and PAT, and select repositories after validation succeeds. Failed validation saves nothing.

<Note>
  Private destinations are supported only when every Weave runtime already has network access, such as a self-hosted Weave deployment on the same private network or VPN. Weave Cloud cannot connect directly to a private-only Azure DevOps Server deployment.
</Note>

Server uses existing polling and sync queues. PR/commit/review/member ingestion feeds Git file hydration, estimates and existing dashboards. Boards uses the same saved collection URL and PAT; configure its selected projects from the Boards connection on the Data page. A successful API connection alone does not prove Git hydration: check a representative merged/squashed PR through clone and estimation on your deployment. Full AI-session remote attribution parity, older Server/TFS and new private-network connectors are outside this release.

For CI, open **Data → CI → Azure Pipelines**, choose Services or Server, and configure pipelines for the selected organization or collection. Server CI requires **Build (read)** and project build access; classic releases additionally require **Release (read)** and project release access. Connecting for CI opens pipeline setup directly without requiring Git repository selection. Builds with external source repositories still need those repositories connected to Weave for production classification; classic releases do not have source repositories.

Unavailable optional release discovery shows a warning while builds remain configurable. If releases are already selected, discovery fails closed rather than silently removing them. Use **Manage Services and Server connections → Rotate PAT** to repair Server authentication or permissions, then retry CI setup; Services continues to use Microsoft OAuth reauthorization.

To replace an expired or revoked PAT, open **Manage Services and Server connections → Rotate PAT**. A replacement is validated before saving and repository selections are retained. Disconnect removes the credential and only that collection's selections; historical analytics remain. PATs are encrypted retrievable secrets, never OAuth grants, and are not returned by GraphQL or stored in Git remote URLs.

## Prerequisites

Before connecting Azure DevOps, you'll need:

* An Azure DevOps organization
* Access to register applications in Microsoft Entra ID
* Permissions to configure firewall rules (if behind corporate firewall)
* HTTPS (port 443) access to required domains

## Connecting Azure DevOps Services (cloud)

<Steps>
  <Step title="Register OAuth application">
    Create a Microsoft Entra ID OAuth application (see detailed setup below)
  </Step>

  <Step title="Start connection">
    Go to **Data** and click **Connect** on Azure DevOps
  </Step>

  <Step title="Authorize Weave">
    Sign in to Microsoft and authorize the Weave application
  </Step>

  <Step title="Select organizations">
    If you have access to multiple Azure DevOps organizations, choose which ones
    to connect
  </Step>

  <Step title="Admin install">
    For organization managers, click **Install** to grant repository sync
    permissions
  </Step>

  <Step title="Select repositories">
    Choose which repositories to sync from your Azure DevOps projects
  </Step>

  <Step title="Wait for sync">
    Initial sync may take several minutes to hours depending on repository size
    and history
  </Step>
</Steps>

## Microsoft Entra ID OAuth setup

This guide walks through creating a Microsoft Entra ID (formerly Azure Active Directory) OAuth application for the Azure DevOps integration.

### Step 1: Navigate to Microsoft Entra admin center

1. Go to the [Microsoft Entra admin center](https://entra.microsoft.com)
2. Sign in with an account that has permission to register applications
3. Navigate to **Identity** → **Applications** → **App registrations**

### Step 2: Register new application

Click **New registration** and configure:

**Application name:**

```
Weave Azure DevOps Integration
```

**Supported account types:**

* **For Azure DevOps Services (cloud):** Select "Accounts in any organizational directory (Multitenant)"

**Redirect URI:**

* Platform: **Web**
* URI: `https://app.workweave.ai/api/azuredevops/oauth/callback`

Replace `app.workweave.ai` with your Weave instance hostname if different.

Click **Register**.

### Step 3: Add additional redirect URI

1. Go to **Authentication** in the left sidebar
2. Under **Web** platform, click **Add URI**
3. Add: `https://app.workweave.ai/api/azuredevops/install/callback`
4. Click **Save**

### Step 4: Create client secret

<Steps>
  <Step title="Navigate to secrets">
    Go to **Certificates & secrets** in the left sidebar
  </Step>

  <Step title="Create new secret">
    Under **Client secrets**, click **New client secret** - Description: `Weave
            Integration Secret` - Expiration: **24 months** (recommended)
  </Step>

  <Step title="Copy secret value">
    Click **Add** and immediately copy the **Value** — it won't be shown again
    Store the secret securely (you'll need it later)
  </Step>
</Steps>

<Warning>
  The client secret value is only shown once. If you lose it, you'll need to
  create a new secret.
</Warning>

### Step 5: Configure API permissions

<Steps>
  <Step title="Add permission">
    Go to **API permissions** → **Add a permission** → **Azure DevOps**
  </Step>

  <Step title="Select delegated permissions">
    Select **Delegated permissions** and check **user\_impersonation**
  </Step>

  <Step title="Grant admin consent (optional)">
    Click **Grant admin consent for \[Your Organization]** to pre-approve for all
    users
  </Step>
</Steps>

The `offline_access` permission is automatically included for refresh token support.

### Step 6: Copy application details

You'll need these values for Weave configuration:

1. **Application (client) ID** — Found on the **Overview** page
2. **Client secret** — Copied in Step 4
3. **Directory (tenant) ID** — Found on the **Overview** page (for single-tenant apps)

For multi-tenant apps (Azure DevOps Services), use `common` as the tenant ID.

## Configure Weave backend

### For Azure DevOps Services (cloud)

Weave administrators need to set these environment variables on the backend:

```bash theme={null}
AZUREDEVOPS_CLIENT_ID="<your-application-client-id>"
AZUREDEVOPS_CLIENT_SECRET="<your-client-secret>"
HOSTNAME="app.workweave.ai"
```

## Permissions required

Weave requests the following Microsoft Entra ID permissions:

* **user\_impersonation** — Full access to Azure DevOps on behalf of the authenticated user
* **offline\_access** — Refresh tokens for automatic token renewal

Access is limited by the authenticated user's permissions within Azure DevOps. If a user can't access a repository, Weave can't sync it.

## OAuth scopes explained

The `user_impersonation` scope grants full access to Azure DevOps APIs on behalf of the authenticated user. This includes:

**Code & repositories:**

* Read and write source code
* Manage repositories and branches
* Access commit history

**Pull requests:**

* Read and write pull requests
* Access reviews and comments
* Manage PR status

**Work items:**

* Read and write work items
* Access work item history

**Team & projects:**

* Read project and team information
* Access organization structure

Access is always limited by your permissions in Azure DevOps. Weave cannot access resources you don't have permission to view.

## Single-tenant vs multi-tenant

**Single-tenant** (a Services OAuth application restricted to one Entra tenant):

* App registered to one specific Entra ID tenant
* Only users from that tenant can authenticate
* Most common for enterprise internal applications

**Multi-tenant** (Azure DevOps Services):

* App can authenticate users from any Entra ID tenant
* Required for ISV applications serving multiple organizations
* Select "Accounts in any organizational directory" during registration

## Multiple organizations

You can connect multiple Azure DevOps organizations from the same or different Microsoft accounts. During the OAuth flow, select all organizations you want to connect.

## Sync frequency

**Services with webhooks:**
Changes typically appear within a few minutes. Azure DevOps webhooks trigger syncs for PR and push events in real-time.

**Polling (Services and Server):**
Existing scheduled sync queues poll connected repositories. Freshness depends on queue load, history size and throttling; initial history may take substantially longer than incremental sync.

**Manual sync:**
Organization admins can trigger manual syncs from the Data page

## Security considerations

**Token storage:**

* Server PATs use application-level AEAD encryption. Do not assume the separate Services OAuth token storage path uses the same field encryption.
* Access tokens expire after \~1 hour
* Refresh tokens expire after \~90 days of inactivity

**Token refresh:**

* Weave automatically refreshes tokens before expiration
* No manual re-authentication required
* You are notified if refresh fails (typically due to revoked access)

**Revoking access:**
To revoke Weave's access:

1. Go to Microsoft Entra admin center
2. Navigate to **Enterprise applications**
3. Find "Weave Azure DevOps Integration"
4. Click **Delete** or disable the application

## Troubleshooting

### Your organization requires admin approval

When someone signs in with Azure DevOps, Microsoft asks them to let Weave read their Azure DevOps data. Many organizations only let Microsoft Entra admins approve new apps. In that case Microsoft shows **Need admin approval** (or the person clicks **Cancel**), and Weave shows an error asking them to contact their admin.

A Microsoft Entra admin (Cloud Application Administrator, Application Administrator or Global Administrator) can approve Weave for the whole organization:

1. Sign in to Weave with Azure DevOps yourself and, on the Microsoft permissions screen, check **Consent on behalf of your organization** before you click **Accept**.
2. Or, if someone has already tried to sign in, go to the [Microsoft Entra admin center](https://entra.microsoft.com) → **Identity** → **Applications** → **Enterprise applications** and open the Weave app. It's named **Weave** for Azure DevOps Services sign-in, or the name you chose (such as **Weave Azure DevOps Integration**) if you registered your own OAuth application above. Then go to **Security** → **Permissions** and click **Grant admin consent for \[your organization]**.
3. If your organization uses the admin consent workflow, approve the pending request under **Enterprise applications** → **Admin consent requests**.

Once Weave is approved, people in your organization can sign in without seeing the approval screen. If Weave is limited to assigned users (**Assignment required** on the Weave enterprise application), also assign the people who need access under **Users and groups**.

See Microsoft's guide to [granting tenant-wide admin consent](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent).

<AccordionGroup>
  <Accordion icon="lock" title="OAuth setup failing">
    If OAuth application setup fails:

    1. Verify you have permission to register applications in Entra ID
    2. Check that both redirect URIs are configured correctly
    3. Ensure the client secret hasn't expired
    4. Confirm user\_impersonation permission is granted
  </Accordion>

  <Accordion icon="link" title="Connection not working">
    If connection to Azure DevOps fails:

    1. Verify environment variables are set correctly in Weave backend
    2. Check that AZUREDEVOPS\_CLIENT\_ID and CLIENT\_SECRET match Entra ID app
    3. Ensure user has access to Azure DevOps organizations
    4. Try revoking and re-granting permissions
  </Accordion>

  <Accordion icon="clock" title="Sync issues">
    If data isn't syncing:

    1. Check that repositories are not archived
    2. Verify user permissions haven't changed
    3. Ensure webhooks are configured (if using)
    4. Trigger manual sync from Data page
  </Accordion>
</AccordionGroup>

## Related documentation

* [Azure DevOps troubleshooting](/troubleshooting/integrations#azure-devops)
* [Microsoft Entra ID OAuth documentation](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/entra)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.