# Connect Azure DevOps

At the end of this guide Volobox reaches your Azure DevOps organization through a Microsoft Entra application your company owns. Its team projects are enabled for Volobox, its repositories can be registered for coding, and project managers can link pipelines and synchronize work items. An administrator with **Manage integrations** and **Manage all code repositories** does the setup, with someone who administers the Entra tenant and the Azure DevOps organization.

## Before you begin

- An Azure DevOps Services organization backed by Microsoft Entra ID. Organizations backed only by personal Microsoft accounts are not supported.
- Permission in Microsoft Entra to create an app registration and a client secret.
- Permission in Azure DevOps to add users to the organization and to each project's **Project Administrators** group.
- A Volobox account with **Manage integrations** (for the connection) and **Manage all code repositories** (for organizations, projects and repositories).

## Create the Entra application

1. In the Microsoft Entra admin center, create an app registration in the tenant that owns your Azure DevOps organization.
2. Add a **Web** redirect URI in this form, with your own Volobox address:

   ```text
   https://volobox.example.com/azure-dev-ops/callback
   ```

3. Create a client secret and copy its value.
4. Note the **Tenant ID** and the application's **Client ID**.

Volobox requests the Azure DevOps delegated `user_impersonation` scope and `offline_access`. The redirect URI is what lets each person connect their own Azure DevOps account later.

> **Note:** Azure DevOps permissions are assigned inside Azure DevOps, not as Entra application permissions. Adding Entra API permissions alone gives Volobox no access.

## Connect Volobox to Azure DevOps

1. In Volobox, open **Admin** on the left activity rail, then **Settings**, and select the **Integrations** tab of **Organization Settings**.
2. Open **Azure DevOps connection**, enter the **Tenant ID**, **Client ID** and **Client secret**, and save. The secret is encrypted and never shown again.
3. In Azure DevOps, add the application's service principal under **Organization settings**, **Users**. Then add it to **Project Administrators** in every project Volobox will use. That group gives Volobox the repository, work-item, pipeline and Service Hooks access it needs.
4. Back in Volobox, open **Code** in **Organization Settings**, then **Azure DevOps organizations**.
5. Enter the organization name, such as `my-organization`, and select **Add organization**. Volobox verifies the organization with a read-only request.
6. Open the organization's menu, select **Manage projects**, enable the team projects Volobox may use, and save.
7. Return to **Integrations** and select **Test credential**.

> **Tip:** Enter the organization name, not a project or repository URL.

![Organization Settings, Code tab: the Manage projects dialog for the meridian-works Azure DevOps organization, with the Harborline and Studio Ops team projects enabled for Volobox and two more left off.](https://volobox.io/docs/images/azure-devops-integration.light.webp)

*The Manage projects dialog for an Azure DevOps organization in Organization Settings, Code: the team projects enabled for Volobox are ticked.*

## Register repositories

1. In **Organization Settings**, open **Code** and select **Register repository**.
2. Choose **Azure DevOps** as the code host.
3. Choose the enabled project and the repository. You can also paste a `dev.azure.com`, legacy `visualstudio.com`, or Azure Repos SSH clone URL.
4. Confirm the name, default branch and sandbox template, then select **Save**.

A Volobox project can then link the repository, start coding sessions on it, and open or update Azure pull requests from a session.

## Connect your own Azure DevOps account

Each person connects their own account so Azure Repos reviews, merges, commits and pushes carry their Azure DevOps identity.

1. Open your avatar menu, select **Settings**, then the **Integrations** tab of **Personal Settings**.
2. Under **Azure DevOps account**, connect your account and sign in to Azure DevOps.

## Link pipelines and work items to a project

A project **Manager** links pipelines on a project with **Coding** turned on.

1. In the project, open **Code**, then **DevOps**, and select **Link Azure DevOps project**.
2. Select one of the Azure DevOps projects an administrator enabled.
3. On the linked project, select **Add pipeline**, pick a pipeline, optionally set **Default branch**, and save.
4. To synchronize work items, open **Work items** on the linked Azure DevOps project and choose whether they arrive as tasks, requests or by automatic routing.

> **Note:** On a project with **Coding** turned off, the project keeps a **DevOps** tab for work-item synchronization only. Pipelines need **Coding** on.

## Check that it works

- **Test credential** passes for every connected organization and its project list. A failure shows on that organization without stopping healthy ones.
- On a linked pipeline, **New deployment** and **Confirm and deploy** start a run. It appears under **Deployments**, and **View in Azure DevOps** opens its logs and stages.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| **Test credential** fails | Check the tenant, client ID and secret, the service principal's organization membership, and project visibility. The connection stays saved with **Needs attention**. |
| Adding the organization returns forbidden or not found | Add the service principal to that organization and grant project access, then try again. |
| No projects are listed | The service principal cannot see any team project in that organization. Add it to **Project Administrators** in the projects Volobox should use. |
| A project shows missing Service Hooks permissions | Add the application to that project's **Project Administrators** group, then reopen the project picker. |
| You changed the Tenant ID or Client ID | Enter the client secret again, save, then select **Test credential**. The saved secret belongs to the previous application. |
| Personal sign-in is not available | Register the Volobox callback URI on the Entra application, then save and test the connection again. |
| A pipeline is missing from the pipeline dialog | Only projects enabled under **Organization Settings**, **Code** can be linked. Enable the project first. |

## Next steps

- [From a task to a pull request](/docs/task-to-pull-request)
- [Coding sessions](/docs/coding)
- [Set up Microsoft Entra ID sign-in](/docs/entra-id-sign-in)
- [Integrations](/docs/integrations)
