Skip to main content
Azure Repos requires an Enterprise plan.
Mintlify connects to Azure Repos through Microsoft Entra ID. You sign in with your Microsoft account so Mintlify can verify which organizations, projects, and repositories you can access. Mintlify then uses the Mintlify app in your Entra tenant to read your repository, create service hooks, deploy every change pushed to your deploy branch, and create preview deployments for pull requests. Mintlify supports Azure DevOps Services organizations on dev.azure.com, including organizations that still use *.visualstudio.com URLs, that are connected to Microsoft Entra ID. Mintlify does not support Azure DevOps Server.

​
Requirements

  • An Azure DevOps organization connected to Microsoft Entra ID.
  • An Entra administrator who grants consent to the Mintlify app in your tenant.
  • The Mintlify app added to your Azure DevOps organization with Basic access, and to the project that contains your repository.
  • The Mintlify app in the project’s Project Administrators group. Azure DevOps only lets project administrators create service hooks.
  • A Microsoft account that is a project administrator or has Manage permissions on the repository you want to connect.
  • Admin access to your Mintlify organization.
  • A docs.json file in your repository.

​
Set up a new Azure Repos connection

When you open Git Settings for the first time, a setup wizard guides you through connecting your repository.
1

Select Azure Repos as your provider

  1. On the Git Settings page, click Connect to Azure Repos.
  2. Click Continue.
2

Move Mintlify-hosted content

If you currently host your content in a Mintlify-managed repository, download it as a zip file. Extract the zip contents and push the files to your Azure Repos repository.If your content is already in Azure Repos, click Continue setup.
3

Connect Microsoft

  1. Click Connect Microsoft.
  2. Sign in with a Microsoft account that is a project administrator or has Manage permissions on the repository you want to connect.
After you sign in, Microsoft redirects you to your Mintlify Git settings.
4

Select the repository

Select the following values. Each list shows the resources your Microsoft account can access.
  • Organization: The Azure DevOps organization. For example, in https://dev.azure.com/acme/docs-project/_git/docs, acme is the organization.
  • Project: The project that contains the repository, such as docs-project.
  • Repository: The repository name, such as docs.
  • Deploy branch: The branch that publishes to your production documentation site, such as main.
5

Configure a content directory (optional)

  1. If your docs.json file is in a subdirectory, enable docs.json is in a subdirectory.
  2. Enter the path to the directory that contains your docs.json file. For example, if your docs.json is in the apps/docs/ directory, enter apps/docs.
6

Connect the repository

  1. Click Connect.
  2. Confirm the change.
Mintlify verifies that your Microsoft account can manage the repository and that the deploy branch exists. Mintlify then registers the service hooks that keep your site and the web editor in sync and starts your first deployment.
To confirm the service hooks, open your Azure DevOps project and go to Project settings > Service hooks. Mintlify creates three Web Hooks subscriptions for the repository: Code pushed, Pull request created, and Pull request updated.

​
Switch an existing deployment to Azure Repos

  1. On the Git Settings page, select Azure Repos as the Git provider.
  2. If you haven’t connected a Microsoft account, click Connect Microsoft and sign in.
  3. Select the organization, project, repository, and deploy branch, and enter a content directory if needed.
  4. Click Switch to Azure Repos.

​
Change the connected Microsoft account

Your entire Mintlify organization shares the Microsoft account in Git Settings, and only admins can change it. Mintlify refreshes Microsoft credentials automatically, so you don’t need to rotate tokens. To use a different account, open the Microsoft connection section on the Git Settings page and click Change account. The new account must be a project administrator or have Manage permissions on the repository.

​
Edit in the web editor

You can edit Azure Repos content in the web editor. When you publish, Mintlify pushes a branch to Azure Repos and opens a pull request against your deploy branch.
  • Branches that you push to Azure Repos sync into the editor.
  • Changes to pull requests in Azure Repos sync into the matching editor branch.
  • When you delete a branch in Azure Repos, Mintlify removes it from the editor.
  • If your deploy branch has blocking branch policies, such as required reviewers, publish through a pull request.

​
Preview deployments

When you open a pull request against your deploy branch, Mintlify builds a preview deployment and links to it from a Mintlify preview ready status on the pull request. Mintlify rebuilds the preview when you push to the pull request’s branch, and deletes it when you complete or abandon the pull request or delete the branch.

​
Use Autopilot

Autopilot works with Azure Repos. It runs when code merges into connected repositories and opens pull requests in your Azure Repos repository. Accept or close its pull requests on the Autopilot page, or merge them in Azure Repos. To give Autopilot more context, connect your source code repositories in Git Settings, then select them in the Azure Repos row of the Autopilot page. See Azure Repos repositories. On Azure Repos, Autopilot does not assign pull requests, request reviews, or respond to pull request comments. To ask for changes, send a message in the suggestion on the Autopilot page.

​
Use the agent in Slack

The agent in Slack works with Azure Repos. When you ask it to update your content, it opens a pull request in your Azure Repos repository.

​
Troubleshooting

Ask an Entra administrator in your tenant to grant consent to the Mintlify app, then connect the repository again.
Mintlify only supports Azure DevOps organizations backed by Microsoft Entra ID. Connect your organization to your Entra tenant in Azure DevOps under Organization settings > Microsoft Entra, then try again.
The Mintlify app can’t read the repository. Add the Mintlify app to your Azure DevOps organization with Basic access, and add it to the project that contains the repository.
Mintlify needs to create service hooks to deploy your changes automatically. Add the Mintlify app to the project’s Project Administrators group, then connect the repository again.
The Microsoft account connected in Git Settings can’t read the repository. Click Change account and sign in with an account that has access. Users with Stakeholder access can’t read repositories in private projects.
The Microsoft account connected in Git Settings can read the repository but can’t manage it. Click Change account and sign in with an account that is in the project’s Project Administrators group or has Manage permissions on the repository.
Check that the branch exists in the repository and that the name matches exactly.
In Azure DevOps, go to Project settings > Service hooks and open the Mintlify subscriptions to check their delivery history. Confirm that you pushed to the deploy branch configured in Mintlify.If a subscription is disabled or missing, click Save in Git Settings. Mintlify replaces any subscription that isn’t healthy.
Mintlify does not remove the service hooks when you switch to a different Git provider. Delete them in Project settings > Service hooks.