跳转到主要内容
Azure Repos 需要 Enterprise 套餐。
Mintlify 通过 Microsoft Entra ID 连接到 Azure Repos。你使用 Microsoft 账号登录，以便 Mintlify 验证你可以访问哪些组织、项目和仓库。随后，Mintlify 使用你 Entra 租户中的 Mintlify 应用读取你的仓库、创建 service hooks、部署推送到部署分支的每一项更改，并为 pull request 创建预览部署。 Mintlify 支持位于 dev.azure.com 且已连接到 Microsoft Entra ID 的 Azure DevOps Services 组织，包括仍在使用 *.visualstudio.com URL 的组织。Mintlify 不支持 Azure DevOps Server。

​
要求

  • 一个已连接到 Microsoft Entra ID 的 Azure DevOps 组织。
  • 一位在你的租户中向 Mintlify 应用授予同意的 Entra 管理员。
  • 已以 Basic 访问级别将 Mintlify 应用添加到你的 Azure DevOps 组织，并添加到包含你仓库的项目中。
  • Mintlify 应用位于该项目的 Project Administrators 组中。Azure DevOps 只允许项目管理员创建 service hooks。
  • 一个是项目管理员或对要连接的仓库拥有 Manage permissions 的 Microsoft 账号。
  • 你的 Mintlify 组织的管理员权限。
  • 仓库中的 docs.json 文件。

​
设置新的 Azure Repos 连接

首次打开 Git Settings 时，设置向导会引导你连接仓库。
1

选择 Azure Repos 作为提供商

  1. 在 Git Settings 页面上，点击 Connect to Azure Repos。
  2. 点击 Continue。
2

迁移 Mintlify 托管的内容

如果你当前将内容托管在 Mintlify 管理的仓库中，请将其下载为 zip 文件。解压 zip 内容，并将文件推送到你的 Azure Repos 仓库。如果你的内容已在 Azure Repos 中，请点击 Continue setup。
3

连接 Microsoft

  1. 点击 Connect Microsoft。
  2. 使用一个是项目管理员或对要连接的仓库拥有 Manage permissions 的 Microsoft 账号登录。
登录后，Microsoft 会将你重定向到 Mintlify 的 Git 设置。
4

选择仓库

选择以下值。每个列表都会显示你的 Microsoft 账号可以访问的资源。
  • Organization：Azure DevOps 组织。例如，在 https://dev.azure.com/acme/docs-project/_git/docs 中，acme 是组织。
  • Project：包含该仓库的项目，例如 docs-project。
  • Repository：仓库名称，例如 docs。
  • Deploy branch：发布到生产文档站点的分支，例如 main。
5

配置内容目录（可选）

  1. 如果你的 docs.json 文件位于子目录中，请启用 docs.json is in a subdirectory。
  2. 输入包含 docs.json 文件的目录路径。例如，如果你的 docs.json 位于 apps/docs/ 目录中，请输入 apps/docs。
6

连接仓库

  1. 点击 Connect。
  2. 确认更改。
Mintlify 会验证你的 Microsoft 账号能否管理该仓库，以及部署分支是否存在。随后，Mintlify 会注册用于保持站点和 Web 编辑器同步的 service hooks，并启动首次部署。
要确认 service hooks，请打开你的 Azure DevOps 项目并前往 Project settings > Service hooks。Mintlify 会为该仓库创建三个 Web Hooks 订阅：Code pushed、Pull request created 和 Pull request updated。

​
将现有部署切换到 Azure Repos

  1. 在 Git Settings 页面上，选择 Azure Repos 作为 Git 提供商。
  2. 如果尚未连接 Microsoft 账号，请点击 Connect Microsoft 并登录。
  3. 选择组织、项目、仓库和部署分支，并在需要时输入内容目录。
  4. 点击 Switch to Azure Repos。

​
更改已连接的 Microsoft 账号

整个 Mintlify 组织共享 Git Settings 中的 Microsoft 账号，且只有管理员可以更改它。Mintlify 会自动刷新 Microsoft 凭据，因此你无需轮换令牌。 要使用其他账号，请在 Git Settings 页面上打开 Microsoft connection 部分，然后点击 Change account。新账号必须是项目管理员或对该仓库拥有 Manage permissions。

​
在 Web 编辑器中编辑

你可以在 Web 编辑器中编辑 Azure Repos 内容。发布时，Mintlify 会将一个分支推送到 Azure Repos，并针对你的部署分支创建 pull request。
  • 你推送到 Azure Repos 的分支会同步到编辑器中。
  • Azure Repos 中 pull request 的更改会同步到编辑器中对应的分支。
  • 当你在 Azure Repos 中删除分支时，Mintlify 会将其从编辑器中移除。
  • 如果你的部署分支设置了阻止性分支策略（例如必需的审阅者），请通过 pull request 发布。

​
预览部署

当你针对部署分支创建 pull request 时，Mintlify 会构建一个预览部署，并通过 pull request 上的 Mintlify preview ready 状态链接到该预览。当你向 pull request 的分支推送时，Mintlify 会重新构建预览；当你完成或放弃 pull request，或删除该分支时，Mintlify 会删除预览。

​
使用 Autopilot

Autopilot 支持 Azure Repos。当代码合并到已连接的仓库时，它会运行并在你的 Azure Repos 仓库中创建 pull request。你可以在 Autopilot 页面上接受或关闭其 pull request，也可以在 Azure Repos 中合并它们。 要为 Autopilot 提供更多上下文，请在 Git Settings 中连接你的源代码仓库，然后在 Autopilot 页面的 Azure Repos 行中选择它们。请参阅 Azure Repos 仓库。 在 Azure Repos 上，Autopilot 不会分配 pull request、请求审阅或回复 pull request 评论。要请求修改，请在 Autopilot 页面上对应的建议中发送消息。

​
在 Slack 中使用 agent

Slack 中的 agent 支持 Azure Repos。当你要求它更新内容时，它会在你的 Azure Repos 仓库中创建 pull request。

​
故障排除

请让你租户中的 Entra 管理员向 Mintlify 应用授予同意，然后重新连接仓库。
Mintlify 仅支持由 Microsoft Entra ID 支持的 Azure DevOps 组织。请在 Azure DevOps 的 Organization settings > Microsoft Entra 中将你的组织连接到 Entra 租户，然后重试。
Mintlify 应用无法读取该仓库。请以 Basic 访问级别将 Mintlify 应用添加到你的 Azure DevOps 组织，并将其添加到包含该仓库的项目中。
Mintlify 需要创建 service hooks 才能自动部署你的更改。请将 Mintlify 应用添加到该项目的 Project Administrators 组，然后重新连接仓库。
Git Settings 中连接的 Microsoft 账号无法读取该仓库。请点击 Change account，并使用有访问权限的账号登录。拥有 Stakeholder 访问级别的用户无法读取私有项目中的仓库。
Git Settings 中连接的 Microsoft 账号可以读取该仓库，但无法管理它。请点击 Change account，并使用属于该项目 Project Administrators 组或对该仓库拥有 Manage permissions 的账号登录。
请检查该分支是否存在于仓库中，以及名称是否完全匹配。
在 Azure DevOps 中，前往 Project settings > Service hooks，打开 Mintlify 订阅以检查其传递历史记录。确认你推送到的是 Mintlify 中配置的部署分支。如果某个订阅已禁用或缺失，请在 Git Settings 中点击 Save。Mintlify 会替换所有状态异常的订阅。
当你切换到其他 Git 提供商时，Mintlify 不会删除这些 service hooks。请在 Project settings > Service hooks 中删除它们。