Repository navigation
Add Azure Repos deployment guide #7720
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,138 @@ | ||
| --- | ||
| title: "Azure Repos" | ||
| description: "Connect an Azure Repos repository to Mintlify with Microsoft Entra ID for automatic deployments, pull request previews, web editor publishing, and Autopilot." | ||
| keywords: ["Azure DevOps", "Microsoft Entra ID", "service hooks", "automated deployments"] | ||
| --- | ||
|
|
||
| <Info> | ||
| Azure Repos requires an [Enterprise plan](https://mintlify.com/pricing?ref=azure-repos). | ||
| </Info> | ||
|
|
||
| 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](https://app.mintlify.com/settings/project/git-settings) for the first time, a setup wizard guides you through connecting your repository. | ||
|
|
||
| <Steps> | ||
| <Step title="Select Azure Repos as your provider"> | ||
| 1. On the [Git Settings](https://app.mintlify.com/settings/project/git-settings) page, click **Connect to Azure Repos**. | ||
| 2. Click **Continue**. | ||
| </Step> | ||
| <Step title="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**. | ||
| </Step> | ||
| <Step title="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. | ||
| </Step> | ||
| <Step title="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`. | ||
| </Step> | ||
| <Step title="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`. | ||
| </Step> | ||
| <Step title="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. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| 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](https://app.mintlify.com/settings/project/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](https://app.mintlify.com/settings/project/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](/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](/deploy/preview-deployments) 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](/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](/autopilot#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](/agent/slack) works with Azure Repos. When you ask it to update your content, it opens a pull request in your Azure Repos repository. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| <AccordionGroup> | ||
| <Accordion title="Mintlify couldn't sign in to your Microsoft Entra tenant"> | ||
| Ask an Entra administrator in your tenant to grant consent to the Mintlify app, then connect the repository again. | ||
| </Accordion> | ||
| <Accordion title="The organization isn't connected to Microsoft Entra ID"> | ||
| 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. | ||
| </Accordion> | ||
| <Accordion title="Add the Mintlify app to the organization or project"> | ||
| 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. | ||
| </Accordion> | ||
| <Accordion title="Add the Mintlify app to the Project Administrators group"> | ||
| 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. | ||
| </Accordion> | ||
| <Accordion title="Your Microsoft account can't access the repository"> | ||
| 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. | ||
| </Accordion> | ||
| <Accordion title="Only a project administrator can connect the repository"> | ||
| 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. | ||
| </Accordion> | ||
| <Accordion title="The deploy branch was not found"> | ||
| Check that the branch exists in the repository and that the name matches exactly. | ||
| </Accordion> | ||
| <Accordion title="Pushes don't trigger a deployment"> | ||
| 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](https://app.mintlify.com/settings/project/git-settings). Mintlify replaces any subscription that isn't healthy. | ||
| </Accordion> | ||
| </AccordionGroup> | ||
|
|
||
| <Note> | ||
| Mintlify does not remove the service hooks when you switch to a different Git provider. Delete them in **Project settings** > **Service hooks**. | ||
| </Note> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For posterity, this is proper punctuation when referring to Azure Repos