Connect Bitbucket
Connect a Bitbucket Cloud repository to Jamdesk. Create a starter docs repo or link an existing one, and every push to your branch deploys your docs.
Jamdesk builds from Bitbucket Cloud the same way it builds from GitHub. Authorize Jamdesk once. Every push to the branch you choose then publishes a new version of your site.
Keeping your docs on GitHub? See Connect GitHub instead. A project connects to one git provider at a time.
Before You Start
- A Bitbucket Cloud account. Bitbucket Data Center and Bitbucket Server are not supported.
- Admin permission on the repository. Jamdesk installs a push webhook on the repository. Bitbucket only lets repository admins create webhooks.
- A project with no repository connected. To move a project from GitHub to Bitbucket, disconnect GitHub first under Settings → Git Repository.
- Popups allowed for the dashboard. The Bitbucket sign-in opens in a popup window.
What Jamdesk Asks For
Jamdesk connects through a Bitbucket OAuth consumer. Bitbucket lists the requested permissions at sign-in:
| Permission | Why Jamdesk needs it |
|---|---|
| Account: Read | Records which Bitbucket account connected the project. Jamdesk recognizes pushes from that account |
| Repositories: Read | Clones your repository to build it. Lists your repositories when you change repository |
| Repositories: Write | Creates the starter docs repository and pushes the starter content into it |
| Webhooks: Read and write | Installs the push webhook that triggers builds. Removes it when the connection changes |
Jamdesk stores the refresh token encrypted with Google Cloud KMS. It renews access on its own. You do not need an app password or a personal access token.
Choose Bitbucket for a Project
Open the project in the dashboard. The project page shows a Connect your docs repository card with two options while no repository is connected. Click Bitbucket.
Let Jamdesk create a starter repository, or connect one you already have.
Create a Starter Docs Repo
Type the workspace slug, the part of your Bitbucket URL after bitbucket.org/. For https://bitbucket.org/acme/, enter acme.
Click Sign in with Bitbucket. A popup opens on bitbucket.org. Review the permissions and grant access.
Jamdesk creates a repository in that workspace, named after your project with a -docs suffix. A project called Acme Docs gets acme-docs. If that name is taken, Jamdesk uses -documentation instead.
The repository starts on the main branch with starter documentation already in place. Jamdesk installs the webhook and runs the first build.
When the card reads Starter docs created and connected!, your site is on its way. Clone the new repository and start editing.
Connect an Existing Repository
Type the repository as workspace/repository-slug, for example acme/developer-docs. Take the workspace and slug from the repository URL on bitbucket.org.
Enter the branch to deploy. Leave it blank to use main.
Click Connect Bitbucket and grant access in the popup. Jamdesk then:
- Confirms your account has admin permission on the repository
- Looks for
docs.jsonin the repository root or a subfolder, up to three levels deep - Installs the push webhook
- Registers your
yourproject.jamdesk.appaddress and starts the first build
The repository needs a valid docs.json on the branch you entered. If Jamdesk finds none, add one and connect again. If it finds more than one, keep one docs.json per repository. A repository with a mint.json is a Mintlify project: run jamdesk migrate on it, push, and connect again.
The connected project card shows the repository, the branch, and a Connected badge.
Automatic Builds on Push
Every push to the connected branch triggers a build:
git add .
git commit -m "Update API documentation"
git push origin mainBitbucket delivers a push event to Jamdesk's webhook. Jamdesk builds that commit once. A duplicate delivery of the same commit does not start a second build. Deleting a branch never triggers a build.
Bitbucket does not retry a webhook delivery that fails. Jamdesk also checks the tip of your branch every five minutes. It builds any commit it has not built yet. A push whose webhook was lost still deploys within a few minutes.
Manual builds from the dashboard work the same as for GitHub projects. See Triggering Builds.
Which Pushes Trigger a Build
Jamdesk builds pushes made by the Bitbucket account that connected the project, or that last re-authorized it. A push from any other account appears in the build list as a failed build with an authorization error. Nothing is deployed.
Bitbucket projects don't yet let you link a personal account in User Settings or authorize extra accounts in Settings → Automation accounts. If several people push to the deploy branch, connect the project with the account that merges to that branch, or have that account do the pushing.
Change the Repository or Branch
Click Change repository on the project card. Jamdesk lists the repositories your Bitbucket account can access. Pick a repository and a branch, then confirm.
Jamdesk installs the webhook on the new repository, removes it from the old one, and starts a build.
Changing repositories affects your live documentation as soon as the build finishes. The new repository must contain a valid docs.json.
Re-authorize an Expired Connection
Bitbucket revokes Jamdesk's access when the connecting user removes it in Bitbucket, or when the refresh token goes unused for several months. The project card then shows a Needs reauth badge and the message Bitbucket connection needs attention.
Click Re-authorize and sign in again. Builds resume. The next five-minute check picks up the latest commit on your branch.
How Bitbucket Differs From GitHub
Bitbucket projects use one OAuth authorization. GitHub projects use a GitHub App plus an optional personal account link. Most of the platform works the same. The differences:
| Feature | GitHub | Bitbucket Cloud |
|---|---|---|
| Build on push | Webhook | Webhook, plus a five-minute check for lost deliveries |
| Starter docs repository | Yes | Yes |
| Custom domains, subpath hosting, manual builds, CLI deploys | Yes | Yes |
| Build status on commits | Shown on the commit in GitHub | Dashboard only |
| Personal account link for build attribution | User Settings | Not available. Builds are attributed to the connecting account |
| Automation accounts allowlist | Settings → Automation accounts | Not yet |
| Web Editor | Yes | Not yet |
| Fix with AI | Yes | Not yet |
| AI Translation | Yes | Not yet |
Deleting a project removes the webhook from your repository and revokes Jamdesk's access.
Troubleshooting
"Your Bitbucket account lacks admin permission on this repository"
Jamdesk needs admin access to install the webhook. Ask a workspace admin to grant you admin permission on the repository, or have an admin connect the project.
"We could not find docs.json in this repository"
Jamdesk looked in the root and up to three folders deep on the branch you entered. Add a docs.json, push it to that branch, and connect again. See the docs.json reference.
"Multiple docs.json files were found"
Keep one docs.json per repository. Remove or rename the others, then connect again.
"This repository looks like a Mintlify project"
The repository has a mint.json. Run jamdesk migrate to convert it, push the result, and connect again.
Popup blocked
Allow popups for the dashboard in your browser, then click Sign in with Bitbucket or Connect Bitbucket again.
Builds not triggering
- In Bitbucket, open Repository settings → Webhooks and confirm the Jamdesk webhook is present and active
- Verify you are pushing to the configured branch
- Wait five minutes. The periodic check builds any commit the webhook missed
- If the project card shows Needs reauth, re-authorize the connection
- If the push came from a different Bitbucket account, see Which Pushes Trigger a Build