Skip to main content

​
What You Can Do

With Azure DevOps connected, Overcut agents can:
  • Access Repositories: Clone, read, and modify code in your Azure DevOps repositories
  • Manage Work Items: Create, update, and comment on Azure DevOps work items (bugs, tasks, user stories)
  • Link Related Work: Create, remove, and review linked relationships between Azure DevOps work items when Azure DevOps allows them
  • Handle Pull Requests: Review, comment on, and manage pull requests
  • Code Operations: Clone repositories, create branches, and perform git operations
  • Webhook Triggers: Automatically start workflows based on Azure DevOps events
  • Repository Configuration: Configure agent behavior per repository

​
How Overcut Authenticates

Overcut authenticates with Azure DevOps using a service principal: an application identity registered in Microsoft Entra ID that authenticates using its own credentials rather than a user’s personal account. For more details on this pattern, see Microsoft’s documentation on service principal authentication in Azure DevOps. Why a service principal?
  • Short-lived tokens: Authentication uses tokens that expire after one hour and are automatically refreshed. No long-lived secrets to rotate
  • No dependency on individual users: The integration is tied to an application identity, not a person’s account, so it survives team member departures and role changes
  • Enterprise security: Centralized permission management through Microsoft Entra ID, with full audit trail and compliance with enterprise security policies
  • Clear attribution: All automated operations appear under a single, recognizable application identity, making it easy to distinguish automated actions from manual ones

​
Before You Start

You need:
  • An Azure DevOps organization that contains the projects you want to connect
  • Your Azure DevOps organization name
  • Your Microsoft Entra tenant ID
  • A Microsoft Entra administrator (Global Admin or Privileged Role Admin) who can approve admin consent
  • An Azure DevOps administrator (Project Collection Administrator) who can add the Overcut service principal to your organization and projects
The Microsoft Entra administrator and Azure DevOps administrator can be different people.

​
Connect Azure DevOps in Overcut

Overcut uses a guided setup flow so you can move through consent, Azure DevOps access, and verification in order.
1

Enter your organization name and tenant ID

In Overcut, open Integrations and choose Connect Azure DevOps.Enter:
  • Organization Name: your Azure DevOps organization name
  • Tenant ID: your Microsoft Entra tenant ID
The tenant ID is a GUID. You can find it in the Microsoft Entra admin center under Overview → Tenant ID, or ask your Entra administrator.Both fields are required before you can continue.
2

Generate the admin consent link

Select Generate link to create the Microsoft admin consent URL for your tenant.Overcut shows the full consent link in the setup flow. You can:
  • Open it yourself if you are the Microsoft Entra administrator
  • Copy it and send it to the administrator who will approve access
The link is generated from the tenant ID you entered, so it is important to confirm that the value is correct before sharing it.
3

Approve consent and return to setup

The Microsoft Entra administrator opens the consent link, reviews the requested access, and approves it for the tenant.
After consent is complete, return to the Overcut setup flow and confirm that admin consent was approved.This step unlocks the Azure DevOps access instructions that follow.
4

Add the Overcut service principal in Azure DevOps

After consent is approved, Overcut shows the service principal ID to use in Azure DevOps.
In Azure DevOps:
  1. Open your organization users page at https://dev.azure.com/<your-organization>/_settings/users
  2. Select Add User
  3. Search for the Overcut service principal using the ID shown in Overcut
  4. Set Access level to Basic
  5. Add the service principal to the Project Administrators group for each project you want to connect
Return to Overcut and confirm that the service principal was added in Azure DevOps.
5

Verify the connection

When admin consent is confirmed and the service principal has been added in Azure DevOps, select Connect in Overcut.Overcut verifies that the service principal can access the Azure DevOps organization you entered. If verification succeeds, the Azure DevOps connection is added to your workspace.

​
What to Expect During Setup

​
Validation

  • Generate link stays unavailable until both Organization Name and Tenant ID are filled in
  • Connect stays unavailable until you confirm both admin consent and service principal setup

​
Verification errors

If the final connection check fails, Overcut shows the verification error in the setup dialog so you can correct the issue and try again. Common reasons include:
  • The service principal was not added in Azure DevOps yet
  • The service principal was added to a different Azure DevOps organization
  • The organization name entered in Overcut does not match the organization the service principal can access

​
Compatibility Note

Overcut uses the modern dev.azure.com format for Azure DevOps. If your team still uses older *.visualstudio.com URLs, enter just your organization name (the same slug that appears in both URL formats) when prompted, then continue with the guided steps.

​
Why Project Administrator Access Is Required

During setup, Overcut instructs you to add the service principal to the Project Administrators group for each project you want to connect. Overcut creates Service Hook subscriptions (webhooks) in Azure DevOps to listen for events such as pull request creation, work item updates, and CI pipeline state changes. These webhooks are what allow Overcut to automatically trigger workflows in response to activity in your Azure DevOps projects. Azure DevOps requires Project Administrator permissions to create and manage Service Hooks. There is no lesser permission level that grants this access. This is an Azure DevOps platform constraint, not an Overcut-specific requirement. If a project is not added during setup, Overcut cannot manage resources or register webhooks in that project until access is granted.

​
Linked work item relationships

Agents can create, remove, and read linked work item relationships in Azure DevOps. Use the relationship types Azure DevOps defines in your connected environment (agents can inspect the available types before linking). Cross-project linking works when Azure DevOps allows it for the projects your workspace can access. See the tools reference for how linked relationships work across providers.

​
Permissions

The Azure DevOps integration requires permissions at two levels, granted during different setup steps. These permissions are approved by the Entra administrator during the admin consent flow:
  • Azure DevOps API access (user_impersonation): Allows the service principal to call Azure DevOps APIs on behalf of the organization
  • Microsoft Graph access: Used for tenant validation during the consent process

​
Azure DevOps permissions (configured when you add the service principal)

These permissions are assigned when the service principal is added to the Azure DevOps organization:
  • Repository Operations: Read and write repository contents, create branches, manage pull requests
  • Work Item Management: Create, read, and update work items (bugs, tasks, user stories, etc.)
  • Service Hook Management: Create and manage webhook subscriptions for event notifications (requires Project Administrator)
  • Project Access: Access to project and organization information

​
Next Steps

After connecting Azure DevOps:
  • Add repositories from the connected organization to your workspace
  • Configure workflows that use repositories, pull requests, and work items
  • Set up triggers that respond to Azure DevOps events
  • Monitor agent activity through Azure DevOps audit logs