Bitbucket
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.
In Archbee, open Organization Settings > Configurations and click the Bitbucket card (Connect Bitbucket account).
On the OAuth tab, click Connect with OAuth, then authorize Archbee in Bitbucket.
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.
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
- Create a new space and select Write in Bitbucket.
- In Select Git Repo, choose the repository. In Select Branch, choose the branch Archbee tracks.
- 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.
Connect an existing space
- Open the space's menu and click Sync with Git App, then Sync with Bitbucket.
- Choose the repository and the branch.
- 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.
- Click Add Space.
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.
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
Edit your documents as drafts. Click Publish Space in the top right corner. In the Update Bitbucket PR row, click Review & Push to PRs.
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.
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.