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)
  • 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

​
Prerequisites

  • An Azure DevOps organization with access to repositories you want to connect
  • A Microsoft Entra ID administrator (Global Admin or Privileged Role Admin) to grant application consent
  • An Azure DevOps Organization Administrator (Project Collection Administrator) to add the service principal — this can be a different person than the Entra ID admin
  • An active Overcut workspace

​
Setup Overview

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
The setup is a two-step process:
  1. Register the app in Microsoft Entra ID — An Entra ID administrator grants consent, which creates a service principal in your tenant.
  2. Add the service principal to Azure DevOps — An Azure DevOps administrator adds the service principal as a user, assigns permissions, and grants project access.

​
Setup Steps

1

Grant Admin Consent in Microsoft Entra ID

Who performs this step: A Microsoft Entra ID administrator (Global Admin or Privileged Role Admin for your tenant). If you’re not an Entra ID admin, coordinate with your IT team for this step.
When you initiate the Azure DevOps connection, Overcut redirects to Microsoft’s admin consent page. The admin reviews and approves the requested permissions, which creates a service principal in your Entra ID tenant.
  1. In your Overcut workspace, go to Integrations
  2. Click Connect Azure DevOps
  3. Enter your Azure DevOps organization name when prompted
  4. You’ll be redirected to Microsoft’s admin consent page
  5. Sign in as a Microsoft Entra ID administrator for your tenant
  6. Review the requested permissions:
    • Azure DevOps API access for repositories, work items, and webhooks
    • Microsoft Graph access for tenant validation
  7. Grant consent for the entire organization
  8. Complete the authorization flow
This creates a service principal in your Microsoft Entra ID tenant and grants it the necessary permissions to access Azure DevOps APIs on behalf of your organization.
2

Add Service Principal to Azure DevOps

Who performs this step: An Azure DevOps Organization Administrator (Project Collection Administrator). This can be a different person than the Entra ID admin from Step 1.
The service principal created in Step 1 must be manually added to your Azure DevOps organization and granted appropriate permissions.
  1. Navigate to Azure DevOps Organization Settings:
    • Go to https://dev.azure.com/{your-org}/_settings/users
  2. Add the Service Principal as a User:
    • Click Add users
    • User or Service Principal: search for d695601a-6888-4810-9ca0-b95bdd2a3842 (Overcut App client ID)
    • Access Level: Select Basic (minimum required for full functionality)
    • Add to projects: select the project(s) you want to connect
    • Azure DevOps Groups: select Project Administrators
    • Click Add
Project Administrator is required. See Why Project Administrator Permissions? below for details.
3

Complete Integration in Overcut

Return to Overcut to finalize the connection. Once the service principal is added to the Project Administrators group, run the connection flow again to complete setup.
  1. After granting admin consent, you’ll be redirected back to Overcut
  2. Overcut will detect the service principal and complete the integration setup
  3. Verify the connection by checking that your Azure DevOps projects appear in the provider list
  4. Add repositories from your Azure DevOps projects
The integration is now complete and ready for use in your workflows.

​
Why Project Administrator Permissions?

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. Without these permissions, Overcut cannot register webhooks and will be unable to automatically respond to Azure DevOps events.

​
Permissions

The Azure DevOps integration requires permissions at two levels, granted during different setup steps.

​
Entra ID Permissions (granted during Step 1)

These permissions are approved by the Entra ID admin 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 during Step 2)

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:
  • Explore repository configuration options for fine-tuned agent behavior
  • Set up workflow triggers to respond to Azure DevOps events
  • Create workflows that leverage both code and work item operations
  • Monitor agent activity through Azure DevOps audit logs