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.comanddev.azure.com, andapp.vssps.visualstudio.com(profile and organization discovery). - For
@openhandscomments 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.- Go to Microsoft Entra ID > App registrations.
- Click New registration.
-
Enter a name such as
OpenHands Azure DevOps. - Select the supported account type for your organization.
-
Add a Web redirect URI:
Replace
<your-auth-hostname>with your installation’s Authentication hostname (auth.<your-openhands-domain>by default), for examplehttps://auth.openhands.example.com/realms/allhands/broker/azure_devops/endpoint. - Click Register.
- Copy the Directory (tenant) ID and Application (client) ID.
- Go to Certificates & secrets and create a client secret. Copy the secret value before leaving the page.
- If your tenant requires explicit API permissions, add the Azure DevOps delegated permission required for user access and grant admin consent.
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:Configure the Admin Console
Pick the path that matches how OpenHands Enterprise is deployed.- Replicated
- Standalone Helm
Open the Replicated Admin Console for your OpenHands Enterprise installation
and go to the application configuration page.In Azure DevOps Authentication:
- Enable Azure DevOps Authentication.
- Enter the Microsoft Entra Tenant ID.
- Enter the Azure DevOps Client ID.
- Enter the Azure DevOps Client Secret.
- 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.
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:
- In the OpenHands web app, go to Settings > Integrations. The Azure DevOps webhooks section lists each Azure DevOps organization you belong to.
- Select Install for each organization that should respond to mentions.
Trigger OpenHands from Azure DevOps
These steps apply to OpenHands Enterprise 0.103.0 and later.
- 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.
automationService.eventForwardingEnabled: true.
To create an automation:
- 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.
- 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.
- 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 aspull_request.openedorpr.*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:
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.

