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

# Bitbucket Cloud

> 将 Bitbucket Cloud 仓库连接到 Mintlify，实现自动化部署、拉取请求预览和持续同步。

<Info>
  Bitbucket Cloud 需要 [Enterprise 套餐](https://mintlify.com/pricing?ref=bitbucket-cloud)。
</Info>

Mintlify 通过 OAuth 连接到 Bitbucket Cloud。当你连接仓库后，Mintlify 会自动部署推送到部署分支的更改，并为拉取请求创建预览部署。

Mintlify 支持托管在 `bitbucket.org` 上的 Bitbucket Cloud 仓库。Bitbucket Data Center、Slack agent 和 automations 不支持 Bitbucket 仓库。

<div id="requirements">
  ## 要求
</div>

* 一个 Bitbucket Cloud 账户
* 在你要连接的仓库中创建 webhook 的权限
* 你的 Mintlify 组织的管理员访问权限
* 你的仓库中有一个 `docs.json` 文件

<div id="set-up-a-new-bitbucket-connection">
  ## 设置新的 Bitbucket 连接
</div>

当你首次打开 [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) 时，设置向导会引导你完成 Bitbucket 仓库的连接。

<Steps>
  <Step title="选择 Bitbucket 作为提供商">
    1. 在 [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) 页面，选择 **Connect to Bitbucket**。
    2. 点击 **Continue**。
  </Step>

  <Step title="迁移 Mintlify 托管的内容">
    如果你目前将内容托管在 Mintlify 管理的仓库中，请将其下载为 zip 文件。解压 zip 内容并将文件推送到你的 Bitbucket 仓库。

    如果你的内容已经在 Bitbucket 中，请点击 **Continue setup**。
  </Step>

  <Step title="授权 Bitbucket">
    1. 点击 **Connect Bitbucket**。
    2. Bitbucket 会打开一个新页面，用于授权 Mintlify 访问你的 Bitbucket 账户。请授权 Mintlify 访问你要连接的仓库。

    授权完成后，Bitbucket 会将你重定向回你的 Mintlify Git 设置。
  </Step>

  <Step title="配置仓库">
    输入以下值：

    * **Workspace**：拥有该仓库的 Bitbucket 工作区的 slug。例如，在 `https://bitbucket.org/acme/docs` 中，`acme` 是工作区 slug。
    * **Repository**：仓库的 slug。例如，在 `https://bitbucket.org/acme/docs` 中，`docs` 是仓库 slug。
    * **Deploy branch**：发布到你的正式文档站点的分支，例如 `main`。
  </Step>

  <Step title="配置内容目录（可选）">
    1. 如果你的 `docs.json` 文件位于子目录中，请在 Git 设置页面启用 **Docs are in a subdirectory**。
    2. 输入包含你的 `docs.json` 文件的目录路径。例如，如果你的 `docs.json` 位于 `apps/docs/` 目录，请输入 `apps/docs`。
  </Step>

  <Step title="连接仓库">
    1. 点击 **Connect**。
    2. 确认更改。Mintlify 会验证已授权的 Bitbucket 账户可以访问你的仓库，并注册用于触发部署和拉取请求预览的 webhook。
  </Step>
</Steps>

<div id="update-an-existing-connection">
  ## 更新现有连接
</div>

1. 前往你的 Mintlify 控制台的 [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) 页面。
2. 展开 **Bitbucket OAuth** 部分。
3. 启用或禁用单个仓库。禁用某个仓库会移除其 Mintlify webhook。

撤销连接会移除通过该账户连接的每个仓库的 Mintlify webhook。

<div id="configure-multiple-repositories">
  ## 配置多个仓库
</div>

你可以将来自多个 Bitbucket 仓库的内容合并到一个站点中。部署中的每个源都必须使用 Bitbucket，并且你必须在 **Bitbucket OAuth** 下启用每个仓库，然后才能将其添加为源。

有关设置说明以及关于 URL 路径、基础源和导航的信息，请参阅 [多仓库部署](/docs/zh/deploy/multi-repo)。

<div id="troubleshooting">
  ## 故障排查
</div>

<AccordionGroup>
  <Accordion title="仓库未授权">
    如果 Mintlify 报告没有已连接的安装可以访问你的仓库，请检查以下内容：

    * 工作区和仓库值使用了正确的 slug，而不是显示名称。
    * 已连接的 Bitbucket 账户具有访问该仓库所需的权限。
    * 你在 Mintlify Git 设置的 **Bitbucket OAuth** 部分中启用了该仓库。

    如果仓库未出现，请使用具有该仓库访问权限的账户重新连接你的 Bitbucket 账户。
  </Accordion>

  <Accordion title="部署未自动触发">
    在 Bitbucket 中，打开 **Repository settings** > **Webhooks**，验证是否存在名为 **Mintlify** 的活动 webhook。如果缺失，请返回你的 Mintlify Git 设置，在 **Bitbucket OAuth** 下禁用该仓库，然后再次启用。

    验证你的 Mintlify Git 设置中的分支与你推送更改的 Bitbucket 分支一致。
  </Accordion>

  <Accordion title="拉取请求预览未出现">
    验证 Mintlify webhook 处于活动状态并包含拉取请求事件。如果你在连接仓库后更改了 Bitbucket 权限，请重新连接你的 Bitbucket 账户并再次启用该仓库。
  </Accordion>
</AccordionGroup>


## Related topics

- [什么是 Mintlify？](/docs/zh/what-is-mintlify.md)
- [创建开发者文档](/docs/zh/guides/developer-documentation.md)
- [文档相关的 Git 概念](/docs/zh/guides/git-concepts.md)