Skip to main content
Bitbucket Cloud requires an Enterprise plan.
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 for the first time, a setup wizard guides you through connecting your Bitbucket repository.
1

Select Bitbucket as your provider

  1. On the Git Settings page, click Connect to Bitbucket.
  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 Bitbucket repository.If your content is already in Bitbucket, click Continue setup.
3

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.
4

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.
5

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.
6

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.

​
Update an existing connection

  1. Navigate to the 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 for setup instructions and information about URL paths, base sources, and navigation.

​
Troubleshooting

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

Related topics

What is Mintlify?Create developer documentationGit concepts for documentation