> ## 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

> Connect a Bitbucket Cloud repository to Mintlify for automatic deployments, pull request previews, and continuous synchronization.

<Info>
  Bitbucket Cloud requires an [Enterprise plan](https://mintlify.com/pricing?ref=bitbucket-cloud).
</Info>

Mintlify connects to Bitbucket Cloud through OAuth. After you connect a repository, Mintlify automatically deploys changes pushed to your deployment branch and creates preview deployments for pull requests.

Mintlify supports Bitbucket Cloud repositories hosted on `bitbucket.org`. Bitbucket Data Center, the Slack agent, and automations do not support Bitbucket repositories.

## Requirements

* A Bitbucket Cloud account
* Permission to create a webhook in the repository you want to connect
* Admin access to your Mintlify organization
* A `docs.json` file in your repository

## Set up a new Bitbucket connection

When you open [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) for the first time, a setup wizard guides you through connecting your Bitbucket repository.

<Steps>
  <Step title="Select Bitbucket as your provider">
    1. On the [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) page, click **Connect to Bitbucket**.
    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 Bitbucket repository.

    If your content is already in Bitbucket, click **Continue setup**.
  </Step>

  <Step title="Authorize Bitbucket">
    1. Click **Connect Bitbucket**.
    2. Bitbucket opens a new page. Authorize Mintlify to access the repository you want to connect.

    After authorization, Bitbucket redirects you to your Mintlify Git settings.
  </Step>

  <Step title="Configure the repository">
    Enter the following values:

    * **Workspace**: The slug of the Bitbucket workspace that owns the repository. For example, in `https://bitbucket.org/acme/docs`, `acme` is the workspace slug.
    * **Repository**: The repository slug. For example, in `https://bitbucket.org/acme/docs`, `docs` is the repository slug.
    * **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 are in a subdirectory** on your Git settings page.
    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 the authorized Bitbucket account can access your repository and registers the webhook that triggers deployments and pull request previews.
  </Step>
</Steps>

## Update an existing connection

1. Navigate to the [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) page of your Mintlify dashboard.
2. Expand the **Bitbucket OAuth** section.
3. Enable or disable individual repositories. Disabling a repository removes its Mintlify webhook.

Revoking a connection removes the Mintlify webhooks for every repository connected through that account.

## Configure multiple repositories

You can combine content from multiple Bitbucket repositories in one site. Every source in the deployment must use Bitbucket, and you must enable each repository under **Bitbucket OAuth** before you add it as a source.

See [Multi-repository deployments](/docs/deploy/multi-repo) for setup instructions and information about URL paths, base sources, and navigation.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Repository not authorized">
    If Mintlify reports that no connected installation can access your repository, check the following:

    * The workspace and repository values use the correct slugs, not display names.
    * The connected Bitbucket account has the necessary permissions to access the repository.
    * You enabled the repository in the **Bitbucket OAuth** section of your Mintlify Git settings.

    If the repository does not appear, reconnect your Bitbucket account with an account that has access to the repository.
  </Accordion>

  <Accordion title="Deployments do not trigger automatically">
    In Bitbucket, open **Repository settings** > **Webhooks** and verify that an active webhook named **Mintlify** exists. If it is missing, return to your Mintlify Git settings, disable the repository under **Bitbucket OAuth**, then enable it again.

    Verify that the branch in your Mintlify Git settings matches the Bitbucket branch you push changes to.
  </Accordion>

  <Accordion title="Pull request previews do not appear">
    Verify that the Mintlify webhook is active and includes pull request events. If your Bitbucket permissions changed after you connected the repository, reconnect your Bitbucket account and enable the repository again.
  </Accordion>
</AccordionGroup>


## Related topics

- [What is Mintlify?](/docs/what-is-mintlify.md)
- [Create developer documentation](/docs/guides/developer-documentation.md)
- [Git concepts for documentation](/docs/guides/git-concepts.md)