Skip to main content
This guide explains how to connect Azure DevOps Services to an OpenHands Enterprise installation. The integration lets users sign in with Microsoft Entra ID, open Azure Repos, create branches and pull requests, and use Azure Boards work items or pull request comments as context for OpenHands workflows.
This guide covers Azure DevOps Services at https://dev.azure.com. Azure DevOps Server is not covered by this integration.

Prerequisites

  • An OpenHands Enterprise installation using Replicated or standalone Helm.
  • A Microsoft Entra administrator who can register an application and create a client secret.
  • An Azure DevOps Services organization, project, and repository.
  • Azure DevOps users with access to the projects and repositories they will use with OpenHands.
  • Network access from OpenHands to login.microsoftonline.com and dev.azure.com, and app.vssps.visualstudio.com (profile and organization discovery).
  • For @openhands comments and automations, network access from Azure DevOps back to the OpenHands app URL, where its Service Hooks deliver events.

Register a Microsoft Entra Application

In the Azure portal, create a Microsoft Entra app registration for OpenHands.
  1. Go to Microsoft Entra ID > App registrations.
  2. Click New registration.
  3. Enter a name such as OpenHands Azure DevOps.
  4. Select the supported account type for your organization.
  5. Add a Web redirect URI:
    Replace <your-auth-hostname> with your installation’s Authentication hostname (auth.<your-openhands-domain> by default), for example https://auth.openhands.example.com/realms/allhands/broker/azure_devops/endpoint.
  6. Click Register.
  7. Copy the Directory (tenant) ID and Application (client) ID.
  8. Go to Certificates & secrets and create a client secret. Copy the secret value before leaving the page.
  9. If your tenant requires explicit API permissions, add the Azure DevOps delegated permission required for user access and grant admin consent.
OpenHands requests the following Microsoft identity scopes during sign-in:

Configure Azure DevOps Access

Make sure the users who will sign in to OpenHands have access to the Azure DevOps organizations, projects, and repositories they need. OpenHands uses the signed-in user’s Azure DevOps access token for repository discovery and Git operations. You don’t configure an organization: each user sees every organization they belong to. Repository names in OpenHands use this format:
For example:

Configure the Admin Console

Pick the path that matches how OpenHands Enterprise is deployed.
Open the Replicated Admin Console for your OpenHands Enterprise installation and go to the application configuration page.In Azure DevOps Authentication:
  1. Enable Azure DevOps Authentication.
  2. Enter the Microsoft Entra Tenant ID.
  3. Enter the Azure DevOps Client ID.
  4. Enter the Azure DevOps Client Secret.
  5. Save and deploy the updated configuration.

Sign In with Azure DevOps

After the deployment is completed, users choose Sign in with Azure DevOps on your app’s login page. On first sign-in, Microsoft may ask the user to consent to the requested permissions. After sign-in, OpenHands stores the user’s Azure DevOps token through the authentication provider so it can list repositories and run Git operations as that user.

Use Azure DevOps Repositories

After signing in, users can select Azure DevOps repositories from the OpenHands repository picker. OpenHands can:
  • List and search Azure DevOps repositories in every organization the signed-in user belongs to. Users who belong to only one organization see only that one.
  • Clone Azure Repos using the signed-in user’s OAuth token. SSH remote URLs (git@ssh.dev.azure.com:v3/...) are also recognized.
  • Read branch and pull request context.
  • Create branches and pull requests.
  • Read and post Azure Repos pull request comments.
  • Read and post Azure Boards work item comments.
OpenHands does not require users to paste a personal access token for Azure DevOps repository access when Microsoft Entra sign-in is configured.

Check Connection and Hook Permissions

A Connected Azure DevOps account means the user has completed Microsoft sign-in. It does not grant permission to create service hooks. The installer needs View subscriptions and Edit subscriptions at the Azure DevOps organization scope. An organization owner or Project Collection Administrator has these permissions; repository access alone is not sufficient. See Microsoft’s ServiceHooks permissions. Hook creation and event delivery use separate network connections: A successful sign-in or installation does not test the last connection. Azure must be able to reach the callback over HTTPS for mentions or automations to run.

Respond to @openhands Comments

OpenHands can respond when someone mentions @openhands in an Azure Repos pull request comment or an Azure Boards work item comment. Service hooks are installed per organization:
  1. In the OpenHands web app, go to Settings > Integrations. The Azure DevOps webhooks section lists each Azure DevOps organization you belong to.
  2. Select Install for each organization that should respond to mentions.
The person installing needs the OpenHands permission to manage integrations and the Azure DevOps permission to create service hooks in that organization (for example, an organization owner or Project Collection Administrator). The hooks cover every project and user in the organization, so one install per organization is enough. OpenHands reads the organization from each event, checks that the commenter has write access to the repository in that organization, and replies in the same pull request or work item. The commenter needs an OpenHands account. Members who cannot view service hooks see OpenHands’ saved installation history. That history does not prove the hooks still exist, are enabled, or can deliver events. A user with View subscriptions can check their current state by opening the webhook section. Only users who can manage hooks see installation actions. Azure DevOps lists only project-level hooks on a project’s Service hooks page, so the organization-wide hooks OpenHands creates do not appear there. An organization owner can list them with an authenticated Azure DevOps REST API request:

Trigger OpenHands from Azure DevOps

These steps apply to OpenHands Enterprise 0.103.0 and later.
Azure DevOps is a built-in event source for OpenHands automations. The hooks installed above also deliver pull request events, so no custom webhook or hand-made Service Hook is needed. Use this for workflows such as:
  • Reviewing every new pull request, or re-reviewing when commits are pushed.
  • Reacting to an approval or a status change on a pull request.
  • Acting on pull request or work item comments that do not mention @openhands.
First, enable Automations in the Admin Console. For Helm installations, follow Automations on Kubernetes, including automationService.eventForwardingEnabled: true. To create an automation:
  1. Install the organization’s hooks in Settings > Integrations as described above. If the section shows Partial, select Reinstall to add the pull request hooks. Older installs may have only the comment hooks.
  2. In Organization Settings > Git Conversation Routing, claim the Azure DevOps organization for your OpenHands team organization. Create the automation in that team organization. If your installation’s only team organization is its default organization, it receives unclaimed events. See Claiming Git Organizations.
  3. Set the Event source to Azure DevOps and the Event key to one of the event types below, or a wildcard such as git.pullrequest.*. These are Azure DevOps’ own event type names; GitHub-style keys such as pull_request.opened or pr.* never match.
An update event does not say what changed, so OpenHands adds the kind of change to the payload as openhands.notificationType: PushNotification, ReviewersUpdateNotification, StatusUpdateNotification or ReviewerVoteNotification. Filter on it to react to one kind of update, for example to run only when a reviewer votes:
To act only on completed pull requests, filter updates on resource.status == 'completed'. The rest of the payload is the Azure DevOps Service Hook event as sent, for example resource.repository.name and resource.pullRequestId. Test with a non-production repository before enabling an automation broadly.

Troubleshooting

If installation fails, collect a support bundle promptly and include the attempt time and any error shown.