Azure DevOps

Connect Azure DevOps so the Autoheal agents can investigate incidents across Azure Repos (code, pull requests, commits), Azure Pipelines (build and release runs and logs), and the Azure DevOps Wiki (runbooks and operational docs). One connection serves all three.

You connect by adding an identity to your Azure DevOps organization — we recommend read access, which gives the agent read-only access. Azure DevOps Services (cloud, dev.azure.com) only.

What the agent can do

Capability	Examples
Browse & search code	clone repositories; read files, history, diffs, blame
Pull requests	review recent PRs and changes
Commits	view commit history and diffs
Pipelines	find recent or failed build & release runs and read their logs
Deployments	trace what changed (build → commit) for a deployment
Wiki	read runbooks and operational documentation

Set up

How you connect depends on where Autoheal runs. Pick your deployment:

Autoheal Cloud (SaaS)

Connect with Microsoft Entra Workload Identity Federation: create an identity in your Microsoft Entra tenant, configure it to trust Autoheal's OIDC issuer, and add it to your Azure DevOps organization with read access. Azure DevOps authorizes on organization membership, not an Azure subscription role.

Prerequisites

• An Azure DevOps Services organization backed by a Microsoft Entra tenant.
• A user-assigned managed identity (recommended) or an Entra app registration, and rights to add it to the organization.
• The issuer, subject, and audience values for your tenant, provided by Autoheal (in the Federated credential reference below).
• Values to enter in Autoheal: your Organization, Directory (Tenant) ID, and the identity's Client ID (optionally a default Project).

Azure CLI

1

Create a user-assigned managed identity

az identity create -g <resource-group> -n autoheal-azuredevops
# note the clientId and tenantId

(Or register an Entra app registration if you require Conditional Access.)

2

Add a federated credential that trusts Autoheal

Use the issuer / subject / audience from the Federated credential reference below:

az identity federated-credential create \
  --name autoheal-federation \
  --identity-name autoheal-azuredevops \
  --resource-group <resource-group> \
  --issuer "<AUTOHEAL_ISSUER>" \
  --subject "<AUTOHEAL_SUBJECT>" \
  --audiences "<AUTOHEAL_AUDIENCE>"

3

Add the identity to your Azure DevOps organization

A Project Collection Administrator adds the identity's service principal under Organization settings → Users, with Basic access and read permission on the relevant projects. It must be in the same Microsoft Entra tenant as the organization. (Microsoft docs)

4

Add the integration in Autoheal

Go to Integrations → Azure DevOps → Workload Identity Federation, enter your Organization, Directory (Tenant) ID, and the identity's Client ID (optionally a default Project), then Test Connection → Save.

Azure Portal

1

Create a user-assigned managed identity

In the Azure Portal → Managed Identities → Create → pick a resource group and name (e.g. autoheal-azuredevops) → Review + create.

2

Add a federated credential that trusts Autoheal

Open the identity → Federated credentials → Add credential → scenario Other issuer, and enter the Issuer, Subject identifier, and Audience from the Federated credential reference below.

3

Add the identity to your Azure DevOps organization

In Azure DevOps → Organization settings → Users → Add users, add the identity's service principal with Basic access and read permission on the relevant projects. It must be in the same Entra tenant as the organization.

4

Add the integration in Autoheal

Go to Integrations → Azure DevOps → Workload Identity Federation, enter your Organization, Directory (Tenant) ID, and the identity's Client ID (optionally a default Project), then Test Connection → Save.

Federated credential reference

Set the federated credential to these values:

• Issuer — https://app.autoheal.ai
• Subject — coming soon on the Autoheal integration page (the per-tenant value Azure matches on sub)
• Audience — <your-tenant-slug>-oidc-service — your Autoheal organization slug followed by -oidc-service

info

Azure validates the assertion's iss / sub / aud against these values, so they must match exactly. Azure accepts a custom audience — it need not be api://AzureADTokenExchange.

Network requirements

• Microsoft Entra → Autoheal's OIDC issuer (/.well-known/openid-configuration + JWKS) — so Entra can validate the federated assertion.
• Agent sandbox → login.microsoftonline.com, dev.azure.com — for az login and read-only API / git calls.

Self-hosted (BYOC)

When you run Autoheal yourself on an Azure VM (Bring Your Own Cloud), connect with the VM's managed identity — the same identity as the Azure Cloud integration. The only difference is that Azure DevOps authorizes on organization membership, not a subscription role.

Prerequisites

• Autoheal running on an Azure VM.
• An Azure DevOps Services organization backed by a Microsoft Entra tenant (Organization settings → Microsoft Entra → Connect directory, if not already).
• Rights to attach a managed identity to the VM and add it to the organization with read access (a Project Collection Administrator).

Azure CLI

1

Point the deployment at a VM managed identity

If you set up the Azure Cloud integration, reuse that identity — its client ID is already in your .env config. Otherwise attach one (see the Azure Cloud page's Self-hosted (BYOC) setup) and set its client ID over SSH:

CLIENT_ID="$(az identity show -g <resource-group> -n autoheal-reader --query clientId -o tsv)"
printf 'AZURE_BYOC_MANAGED_IDENTITY_CLIENT_ID=%s\n' "$CLIENT_ID" | sudo tee -a /opt/autoheal/.env

No subscription role is needed for Azure DevOps.

warning

Write the resolved GUID into .env — don't paste AZURE_BYOC_MANAGED_IDENTITY_CLIENT_ID=$(az identity show …) literally; the .env file isn't a shell. A system-assigned identity needs no variable.

2

Add the identity to your Azure DevOps organization

A Project Collection Administrator adds the identity under Organization settings → Users with Basic access and read permission on the relevant projects. It must live in the same Microsoft Entra tenant as the organization. (Microsoft docs)

3

Add the integration in Autoheal

Go to Integrations → Azure DevOps → Managed Identity, enter your Organization (and an optional default Project), then Test Connection → Save.

Azure Portal

1

Point the deployment at a VM managed identity

Reuse the Azure Cloud integration's VM identity if you have one. Otherwise attach one in the Portal (see the Azure Cloud page's Self-hosted (BYOC) setup). Copy its Client ID (open the managed identity → Properties) and add it to your .env config over SSH:

# /opt/autoheal/.env
AZURE_BYOC_MANAGED_IDENTITY_CLIENT_ID=<client-id-guid>

A system-assigned identity needs no variable. No subscription role is needed for Azure DevOps.

2

Add the identity to your Azure DevOps organization

In Azure DevOps → Organization settings → Users → Add users, add the identity's service principal with Basic access and read permission on the relevant projects. It must be in the same Entra tenant as the organization.

3

Add the integration in Autoheal

Go to Integrations → Azure DevOps → Managed Identity, enter your Organization (and an optional default Project), then Test Connection → Save.

info

The agent sandbox runs as a container on the VM and reaches the identity through the local metadata service at 169.254.169.254, then calls dev.azure.com over the internet. If Test Connection fails, confirm the metadata service from inside a sandbox container:

curl -s -H "Metadata: true" \
  "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=499b84ac-1321-427f-aa17-267ca6975798"

A JSON token response means it works.

Limitations

• Azure DevOps Services (cloud) only. Only dev.azure.com is supported. On-prem Azure DevOps Server is not supported, and legacy <account>.visualstudio.com URLs aren't accepted (those orgs are reachable as dev.azure.com/<org>).
• One organization per integration — add one per org. Each integration connects a single Azure DevOps organization. To cover several, add a separate integration for each, all using the same identity (add that identity to each organization with read access). The agent passes --org per command, so multiple organizations coexist.
• Access is what you grant. Add the identity to the organization with read access for read-only use; the agent's access is exactly what that org permission allows.
• One identity for everything. Use the same identity across all your Azure DevOps organizations and the Azure Cloud integration — add it to each org with read access, and grant it Reader on your Azure subscriptions. One identity, one Client ID, used everywhere: the agent's sandbox shares one az session, so two different identities would conflict.

info

This is the Azure DevOps integration (dev.azure.com). It is separate from the Azure Cloud integration (management.azure.com — infrastructure). Both use the az CLI but are distinct integrations with independent access grants.

Example questions

Once connected, you can ask the agent:

What changed in the last deployment to production?

Show me recent commits to the payments service repo

Why did the latest build of the checkout pipeline fail?

Find the runbook for database failover in the wiki

Troubleshooting

Managed Identity: Test Connection fails / metadata service unreachable

Confirm the managed identity is attached to the Autoheal VM and that the sandbox can reach 169.254.169.254 (see the check above). For a user-assigned identity, confirm AZURE_BYOC_MANAGED_IDENTITY_CLIENT_ID in .env is a concrete GUID (not a $(…) command) and that you restarted Autoheal.

WIF: Test Connection fails with AADSTS70021

The federated credential's issuer / subject / audience don't match Autoheal's, or it was just created. Re-check them against the Federated credential reference in the Autoheal Cloud (SaaS) tab and retry shortly — propagation can take a few minutes.

401 Unauthorized / 403 Forbidden

Confirm the identity was added to the organization with read access and is in the same Entra tenant. Verify the Organization value matches your dev.azure.com/<org> URL.

404 Not Found

Verify the project or repository exists and the identity has access; check the Organization value.

Rate limited (429)

Azure DevOps applies per-organization throttling; respect the Retry-After header and retry.