Azure DevOps Repositories

By integrating Azure DevOps Repositories with DX, you can analyze pull requests and repositories. Please refer to the API documentation below and our schema explorer to see what data DX imports—note that DX does not read or access your source code.

In addition to the Azure DevOps Repositories connector, you can set up additional connectors for Azure DevOps Boards, Azure DevOps Pipelines, Azure DevOps Pull Commits, and Azure DevOps Commits (Default branch). Each credential has its own authentication settings. Azure DevOps applies rate limits to service principals as it does to users, so plan credential identities and permissions for your expected load.

Prerequisites

For Azure DevOps Services (cloud), choose a personal access token (PAT) or a Microsoft Entra service principal authenticated with a client secret or certificate. Your Azure DevOps organization must be connected to the Entra tenant that contains the service principal. Azure DevOps Server supports PAT authentication only.

Setup instructions

Follow the steps for your authentication method, then create the Azure DevOps Repositories connection in DX.

Personal access token

Step 1

1. Go to the Azure portal and create a service account in Microsoft Entra ID (formerly Azure Active Directory).
2. Then, assign the service account to an ADO organization and grant them permissions.
   • See Add organization users and manage access and Security groups, service accounts, and permissions reference for more information.

Step 2

1. Log into ADO using the service account
2. Generate a Personal Access Token with the read permissions outlined below:

Step 3

• Navigate to the connections page in DX and select “+ Connection” in the top right.
• Select Personal access token (PAT) and enter the token. Refer to the information below for errors and troubleshooting.

Microsoft Entra service principal (Azure DevOps Services)

For Azure DevOps Services (cloud), follow the Microsoft Entra authentication setup guide. It covers the shared configuration for all Azure DevOps cloud connectors. Azure DevOps Server supports PAT authentication only.

Webhooks

DX supports Azure DevOps webhooks ingestion to sync pull request data in real-time. This is recommended in order to ensure real-time data accuracy in DX.

You can enable webhooks via the Azure DevOps API, or through the UI.

API-based setup

Run the CURL command three times for each project where you want to enable webhooks—once each for git.pullrequest.created, git.pullrequest.updated, and git.pullrequest.merged:

curl --location 'https://dev.azure.com/${your_organization}/_apis/hooks/subscriptions?api-version=7.1' \
--header 'Authorization: Basic ${token}' \\
--data-raw '{
    "consumerActionId": "httpRequest",
    "consumerId": "webHooks",
    "consumerInputs": {
        "url": "${your_url}/webhooks/ado",
        "httpHeaders": "X-ADO-Signature:${webhook_token}" # Replace this token with webhooks secret from DX, found on the Connections admin page
    },
    "eventType": "git.pullrequest.created",
    "publisherId": "tfs",
    "publisherInputs": {
        "repository": "",
        "branch": "",
        "pullrequestCreatedBy": "",
        "pullrequestReviewersContains": "",
        "projectId": "${project_id}",
    },
    "resourceVersion": "1.0",
    "scope": 1
}'

UI-based setup

To enable webhooks via the UI:

1. Navigate to Project Settings > Service Hooks
2. Click the ”+” icon and choose Service “Webhooks” to add a new webhook.
3. Here’s what your settings should look like:

API reference

The table below lists the specific API endpoints that are used by DX.

Curl commands

When DX verifies an Azure DevOps Repositories connection, it checks specific endpoints to ensure proper access. The curl commands below use a PAT. For an Entra credential, verify the connection in DX; a direct API request requires an Entra access token in the Authorization: Bearer header instead of -u :YOUR_PAT. See Microsoft’s Azure DevOps token request example.

curl -u :YOUR_PAT -H 'Accept: application/json' 'https://dev.azure.com/YOUR_ORGANIZATION/_apis/projects?api-version=7.0'

curl -u :YOUR_PAT -H 'Accept: application/json' 'https://dev.azure.com/YOUR_ORGANIZATION/_apis/graph/users?api-version=7.0'

curl -u :YOUR_PAT -H 'Accept: application/json' 'https://dev.azure.com/YOUR_ORGANIZATION/_apis/git/repositories?projectId=YOUR_PROJECT_ID&api-version=7.0'

If you receive a 401 Unauthorized error, check the PAT or Entra credential. If you receive a 403 Forbidden error, check the identity’s Azure DevOps organization, project, and resource access. If you receive a 404 Not Found error or empty results, check the organization name and project access.

Note about Authentication: The -u :YOUR_PAT flag uses curl’s built-in basic authentication with an empty username and your Personal Access Token as the password. This automatically handles the Base64 encoding required for Azure DevOps authentication.

Errors

The table below lists potential error codes when adding a connection in DX.

Data Cloud API

Once the initial connection is created successfully, Azure DevOps credentials can be managed via the Data Cloud API.

• credentials.create
• credentials.update
• credentials.info
• credentials.list
• credentials.delete

Credential fields

Use exactly one method per credential: pat with a PAT; client_secret with a tenant ID, client ID, and client secret; or certificate with a tenant ID, client ID, public certificate, and private key. Credential API responses omit the secret and private key. Each credential can have its own app registration and authentication method. For the API, send the fields in settings and secrets when you create a credential. After saving, use Verify in DX to check access. Verification of a saved credential can reuse its stored secret or private key.

Example client secret credential:

{
  "label": "Azure DevOps client secret",
  "settings": {
    "strategy": "client_secret",
    "tenant_id": "<directory-tenant-id>",
    "client_id": "<application-client-id>"
  },
  "secrets": { "client_secret": "<client-secret-value>" }
}

Example certificate credential (the PEM fields contain the full certificate and private key, including their BEGIN and END lines):

{
  "label": "Azure DevOps certificate",
  "settings": {
    "strategy": "certificate",
    "tenant_id": "<directory-tenant-id>",
    "client_id": "<application-client-id>",
    "public_certificate_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "secrets": {
    "private_key_pem": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  }
}

Example PAT credential creation:

{
  "label": "Azure DevOps PAT",
  "settings": { "strategy": "pat" },
  "secrets": {
    "personal_access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}