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

# Azure DevOps

> Connect Azure DevOps Services projects, work items, repositories, builds, and pipelines to Serval.

Connect an Azure DevOps Services organization to read projects, query and update
work items, manage pull requests, and start or inspect builds and pipeline runs.
The connection uses the Azure DevOps API. Microsoft Graph and Azure Resource
Manager connections do not provide these operations.

## Choose authentication

Use a Microsoft Entra service principal for unattended automation, or an
organization-scoped personal access token (PAT). Both methods use the permissions
granted to that identity in Azure DevOps. Serval stores the credential encrypted.

### Microsoft Entra service principal

1. In the Microsoft Entra tenant connected to your Azure DevOps organization,
   create an app registration. Save its **Directory (tenant) ID** and
   **Application (client) ID**.
2. Create a client secret and save its **Value**, not the secret ID. Set an
   expiration and plan to replace the credential in Serval before it expires.
3. Add the service principal explicitly to your Azure DevOps organization. If
   using the Azure DevOps API to add it, use the object ID from **Enterprise
   applications**, not the object ID of the app registration.
4. Grant the required Azure DevOps access level and project permissions. Repository
   access generally requires Basic access. Membership in an Entra group alone does
   not add a service principal to the organization.

Serval requests the Azure DevOps resource scope
`https://app.vssps.visualstudio.com/.default`. Azure DevOps authorizes the service
principal using its own permissions; Microsoft Graph application permissions do
not grant Azure DevOps access. See Microsoft's
[service principal guide](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity?view=azure-devops).

### Personal access token

In Azure DevOps, open **User settings > Personal access tokens** and create a token
for the specific organization. Give it **Project and Team: Read** for the connection
check, then only the scopes required by your workflows:

| Workflow operation | PAT scope |
| - | - |
| Read or query work items | Work Items: Read |
| Create or update work items | Work Items: Read & write |
| Read repositories and pull requests | Code: Read |
| Create or update pull requests | Code: Read & write |
| Read builds and pipelines | Build: Read |
| Queue builds or run pipelines | Build: Read & execute |

A PAT also depends on its owner's project permissions and continued access. Use a
short expiration and rotate it in Serval. See Microsoft's
[PAT guide](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops).

## Connect in Serval

1. Open **Integrations**, find **Azure DevOps**, and choose **Connect**.
2. Choose the authentication method.
3. Enter the organization name from `https://dev.azure.com/contoso`, for example
   `contoso`, without the URL or project path.
4. For a service principal, enter the tenant ID, application ID and client secret.
   For a PAT, enter the token. Choose **Connect**.

The connection check reads one page of visible projects. A successful check does
not establish permission to write work items, access every repository, or run a
pipeline. Each workflow operation is authorized by Azure DevOps.

## Workflow behavior

The SDK's `azureDevOps.apiRequest` returns `{ body, headers }`. Projects, builds,
and pipelines may return `x-ms-continuationtoken`; pass that value as the next
request's `continuationToken`. Pull-request lists use `$top` and `$skip`. Work-item
lists accept up to 200 IDs per request. Query work items with WIQL and then fetch
the returned IDs. The connector preserves response headers and does not fetch
additional pages automatically.

Work-item create and update calls use JSON Patch. For an update that depends on a
specific revision, include a `test` operation against `/rev` before the changes.
Workflows can update work-item fields, relations, and history. Pipeline and build
execution can run code and deployments; grant execute permissions only when needed.

This connector targets Azure DevOps Services API 7.1. The initial API set covers
projects, work items, Git repositories and pull requests, builds, and pipelines.
Azure DevOps Server, Releases, Artifacts, identity provisioning, service hooks,
certificate authentication, managed identity and federation are not included.

## Troubleshooting

* **Authentication fails:** Check credential expiration, tenant/application IDs,
  organization name and identity membership. For a PAT, check that it is scoped to
  this organization and its owner still has access.
* **403 or missing projects:** Check the identity's Azure DevOps access level,
  project membership and endpoint permissions. A valid token grants no additional
  permissions by itself.
* **Reconnect or rotate:** Choose the existing authentication method and replace
  the credential. Leaving the masked value unchanged preserves the saved secret.
  Re-enter the credential when changing the method, tenant or app. To use a
  different Azure DevOps organization, create a new connection.
* **429 or rate-limit delays:** Inspect Azure DevOps response and retry headers;
  reduce request volume and follow Microsoft's
  [rate-limit guidance](https://learn.microsoft.com/en-us/azure/devops/integrate/concepts/rate-limits?view=azure-devops).


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