> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps integration

> Connect Azure DevOps repositories to env zero for IaC template creation, requiring Basic access level and View permissions for the organization.

<Warning>
  To integrate with Azure DevOps, you need an Azure DevOps user with `Basic` access level on the necessary Azure DevOps organization and `View permissions for this node` permission for the project. We recommend that this user be a designated shared bot user, as env zero will perform actions as this user on the project/repository.

  If you do not have the correct permissions, ask an administrator or a different user with those permissions to create the template.
</Warning>

## Prerequisites

Before creating an Azure DevOps template, you need an Azure DevOps VCS connection configured in your organization. To set one up, go to **Organization Settings > VCS** and create a new Azure DevOps connection.

Learn more: [Managing VCS Connections](/guides/admin-guide/manage-vcs#centralized-management)

## Microsoft Entra ID authentication

Microsoft is [retiring Azure DevOps OAuth apps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/azure-devops-oauth) in 2026. env zero connects to Azure DevOps through Microsoft Entra ID instead.

New Azure DevOps connections use Microsoft Entra ID by default. Connections created before the change use Azure DevOps OAuth until you switch them.

<Warning>
  Microsoft Entra ID supports work or school accounts only. Personal Microsoft accounts, such as `outlook.com` or `live.com` accounts, cannot authorize a connection.
</Warning>

### Switch an existing connection

**Required permission:** Edit Organization Settings.

<Steps>
  <Step title="Find connections that need to switch">
    Go to **Organization Settings > VCS**. Azure DevOps connections that still use Azure DevOps OAuth show an exclamation mark next to the provider logo. In the **Configure VCS Connection** window, the **Deployment** card shows a **Needs attention** tag.
  </Step>

  <Step title="Open the connection details">
    Open the connection and click **Edit**. The method the connection uses is tagged **In use**.
  </Step>

  <Step title="Select Microsoft Entra ID">
    Select **Microsoft Entra ID (recommended)** and click **Grant Access**.
  </Step>

  <Step title="Sign in as the same user">
    Sign in with the Azure DevOps user who created the connection. If you sign in as a different user, env zero shows "Sign in as `<USER>` to switch this connection." and the connection does not change.

    Microsoft can sign you in with the account your browser is already signed in to. If that is a different user, retry from a private browser window.
  </Step>

  <Step title="Finish the switch">
    After the sign-in, env zero shows "Switched to Microsoft Entra ID." Click **Done**.
  </Step>
</Steps>

The connection keeps its ID, so templates, environments, and webhooks that use it keep working. The previous Azure DevOps OAuth credentials are replaced.

### Admin consent

If your Microsoft Entra tenant does not let users consent to apps, the sign-in fails with "Your Microsoft Entra administrator must grant consent to env0 before you can connect Azure DevOps."

A tenant administrator grants consent once for the whole tenant. Send them this link:

```text theme={null}
https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=ace5b564-6a75-4df7-9309-9bd93f0969a4&scope=499b84ac-1321-427f-aa17-267ca6975798/vso.code%20499b84ac-1321-427f-aa17-267ca6975798/vso.code_status%20499b84ac-1321-427f-aa17-267ca6975798/vso.notification_write%20499b84ac-1321-427f-aa17-267ca6975798/vso.threads_full%20offline_access&redirect_uri=https://webhooks.api.env0.com/vcs-authorize/oauth/redirect
```

The administrator signs in, reviews the permissions, and clicks **Accept**. env zero then shows "Microsoft Entra admin consent was granted to env0. You can close this tab." After that, retry the switch.

The link requests these Azure DevOps permissions:

| Permission | Used for |
| - | - |
| `vso.code` | Read repositories and code |
| `vso.code_status` | Report commit and pull request statuses |
| `vso.notification_write` | Manage service hooks for webhooks |
| `vso.threads_full` | Comment on pull requests |
| `offline_access` | Keep the connection authorized without signing in again |

### Reauthorization

If env zero does not use a Microsoft Entra ID connection for 90 days, Microsoft expires its authorization, and actions that use the connection fail. To authorize it again, open the connection, select **Microsoft Entra ID (recommended)**, and click **Grant Access** with the same user.

### FAQ

<AccordionGroup>
  <Accordion title="Why is my connection marked?">
    The connection uses Azure DevOps OAuth, which Microsoft is retiring. [Switch it to Microsoft Entra ID](#switch-an-existing-connection).
  </Accordion>

  <Accordion title="What happens if I don't switch?">
    The connection keeps using Azure DevOps OAuth, and env zero can't guarantee it keeps working. Microsoft [scheduled Azure DevOps OAuth for removal in 2026](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/azure-devops-oauth) and can stop it on its own schedule. When that happens, templates and environments that use the connection stop working until you switch.
  </Accordion>

  <Accordion title="Can I switch using a different Azure DevOps user?">
    No. Sign in as the user who created the connection. To use a different user, create a new connection and update your templates to use it.
  </Accordion>

  <Accordion title="Why is the sign-in rejected when I use the right user?">
    env zero matches the user by the Azure DevOps display name saved when the connection was created. If that user changed their display name since, the switch is rejected. Change the display name back to the one shown in the error, or contact env zero support.
  </Accordion>

  <Accordion title="Why does the connection still show the mark after I switched?">
    If env zero shows "Connection status not refreshed", the switch worked but the connection still shows its old method. Click **Grant Access** again with the same user.
  </Accordion>

  <Accordion title="What if my administrator blocks the sign-in?">
    Your tenant requires admin consent. Send your Microsoft Entra administrator the [admin consent link](#admin-consent).
  </Accordion>
</AccordionGroup>

## New Template

<Steps>
  <Step title="Create Template">
    Click **ADD A NEW TEMPLATE** on the top right in the *Templates* screen. Pick your template type, enter a name for the template, and click **NEXT**.
  </Step>

  <Step title="Select Azure DevOps">
    Click on the **Azure DevOps** button.
  </Step>

  <Step title="Select VCS Connection">
    Select a pre-configured Azure DevOps VCS connection from the dropdown. If no connection exists, click **Add VCS Connection** to create one.
  </Step>

  <Step title="Select Repository">
    Pick the repository from the list of accessible Azure DevOps projects.
  </Step>

  <Step title="Configure Source">
    If you would like to pull the code from a specific revision or branch, enter that in the `Branch` field. Leaving this field empty will use your default branch, which is usually "master"/"main".

    Enter the folder your IaC files are located in under the IaC type folder. If your IaC files are in the root of the repository, leave this empty.
  </Step>

  <Step title="Configure Variables">
    Click **NEXT** to proceed to the variables section. Add environment and Terraform variables that you'd like to be used during deployment, and then click **NEXT** to go to the final "Projects" section.
  </Step>

  <Step title="Assign Projects">
    Pick the projects that you'd like to have access to deploy this template, and then click **DONE** to create the template.
  </Step>
</Steps>

<Warning>
  Troubleshoot

  * Can't find your repository? Verify that the VCS connection has access to the necessary Azure DevOps organization/project. You can check the available repositories in **Organization Settings > VCS** by selecting the relevant connection.
</Warning>

<Warning>
  **Azure DevOps old domain name URLs**

  Repositories using the old domain name URLs are not supported, i.e., if the URL for your git repository is in the format of `<organization-name>.visualstudio...` an environment won't be created.

  For more information about old domain name URLs and how to resolve the issue, read [here](https://learn.microsoft.com/en-us/azure/devops/release-notes/2018/sep-10-azure-devops-launch#switch-existing-organizations-to-use-the-new-domain-name-url).
</Warning>

## Existing Template

If you would like to integrate an existing template with Azure DevOps:

1. From the **Templates** screen, click on **Settings** for the appropriate template you would like to integrate with Azure DevOps.
2. Click on the **VCS** step. From there you can click on the **Azure DevOps** button, and integrate with Azure DevOps as you would for a new template.

<Info>
  Additional Content

  * [Managing Terraform variable hierarchy](https://www.envzero.com/blog/managing-terraform-variable-hierarchy)
  * [Why env zero is a Terraform Cloud alternative?](https://www.envzero.com/alternatives/terraform-cloud-vs-envzero)
</Info>

## Next steps

* [Managing VCS](/guides/admin-guide/manage-vcs) - Manage all VCS provider connections in one place.
* [Standard GitHub integration](/guides/admin-guide/templates/github-templates) - Connect GitHub as an alternative VCS provider.
* [Running plan on pull requests](/guides/admin-guide/environments/plan-on-pull-request) - Trigger plans automatically from pull requests.
* [Template overview](/guides/admin-guide/templates) - Learn how templates are structured and configured.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.