--- title: Bitbucket slug: docs/bitbucket createdAt: 2026-10-20T10:00:00.000Z --- Connect a Bitbucket account to Archbee, then sync its repositories to doc spaces. Archbee works with Bitbucket Cloud (bitbucket.org). Bitbucket Data Center and Bitbucket Server are not supported. Only organization admins in Archbee can connect Bitbucket. ## Connect Bitbucket Archbee connects to Bitbucket as one Bitbucket user. It can sync the repositories in the workspaces that this user can access. To let Archbee add the webhooks that keep spaces in sync, the user needs admin access to those repositories. ::::WorkflowBlock :::WorkflowBlockItem In Archbee, open **Organization Settings** > **[Configurations](https://app.archbee.com/settings/team-integrations)** and click the **Bitbucket** card (*Connect Bitbucket account*). ::: :::WorkflowBlockItem On the **OAuth** tab, click **Connect with OAuth**, then authorize Archbee in Bitbucket. ::: :::WorkflowBlockItem After you authorize Archbee, you return to **Configurations**, and the Bitbucket card shows **Connected**. Open the card to see your repositories, grouped by workspace. ::: :::: ### Connect with an app password instead The **App Password** tab connects with a Bitbucket username and app password instead of OAuth. Enter them in **Username** and **App Password**, then click **Connect**. Give the app password access to your account, workspace membership, repositories, pull requests and webhooks, with write access to repositories, pull requests and webhooks. :::hint{type="warning"} Atlassian is retiring app passwords in favor of API tokens. If you cannot create an app password, connect with OAuth. With an app password, **Refresh Bitbucket data** does not work. To load new repositories, connect again. ::: To switch between OAuth and an app password, connect with the other tab. Archbee then removes the credentials of the method you used before. ## Create a space from a Bitbucket repository 1. Create a new space and select **Write in Bitbucket**. 2. In **Select Git Repo**, choose the repository. In **Select Branch**, choose the branch Archbee tracks. 3. Click **Add Space**. You can also click the **+** button (*Create synced space*) next to a repository in the Bitbucket card. Choose a **Space group** and a branch, then click **Create space**. When the import finishes, Archbee notifies you. If the repository has no Archbee config file yet, Archbee also opens a pull request titled **Setup for Archbee-powered Docs** with an `archbee.json` file and starter pages. To configure the repository yourself, see [Set up the repository](docId\:fsqc31Wq96DYg7y-vml_H). ## Connect an existing space 1. Open the space's menu and click **Sync with Git App**, then **Sync with Bitbucket**. 2. Choose the repository and the branch. 3. If the repository has no `archbee.json` yet, follow **Let's configure your repo**: create the pull request, open it in Bitbucket, merge it, then click **Check if merged**. 4. Click **Add Space**. :::hint{type="warning"} Connecting a space to a repository replaces the content of the space with the content of the repository. Try it on a copy of the space first. ::: ## Keep the space in sync Archbee adds a webhook to the repository. Each push to the tracked branch starts a sync. While auto-merge is off, which is the default, each push waits for review in Archbee. See [Review incoming git changes](https://www.archbee.com/docs/review-incoming-git-changes). To change how the space syncs, open **Space settings** > **Bitbucket Integration**: - **Git branch** sets the branch Archbee tracks and opens pull requests on. Changing it takes publish rights on the space. - **Auto-merge pushes** sets whether pushes apply right away or wait for review. - **Sync from repo** replaces the space with the content of the repository right away, even when auto-merge is off. ## Send Archbee drafts to Bitbucket ::::WorkflowBlock :::WorkflowBlockItem Edit your documents as drafts. Click **Publish Space** in the top right corner. In the **Update Bitbucket PR** row, click **Review & Push to PRs**. ::: :::WorkflowBlockItem Review your changes, then click **Push to Bitbucket PR**. Archbee opens a pull request against the tracked branch, or updates the one it already opened. ::: :::WorkflowBlockItem Review and merge the pull request in Bitbucket. Archbee deletes the drafts that went into it and syncs the merged content. While auto-merge is off, the merged content waits for review in Archbee first. If you decline the pull request, Archbee keeps the drafts. ::: :::: ## Disconnect Bitbucket To disconnect one space, open **Space settings** > **Bitbucket Integration** and click **Remove Bitbucket integration**. To disconnect the whole organization, click **Remove Integration** at the bottom of the Bitbucket card, then confirm. Archbee removes its webhooks from the repositories, disconnects every space that synced from Bitbucket and deletes the stored credentials. The spaces keep their content. ## Differences from GitHub - Each sync downloads every file in the docs folder again, and imports OpenAPI files again, so syncs of large repositories take longer than on GitHub. - Archbee does not follow a repository or a workspace that you rename in Bitbucket. - Archbee connects as one Bitbucket user, not as an app installed on a workspace.