Skip to main content
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.

​
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: 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.

​
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.