Connect a Bitbucket repository so Hamster answers from your code and you can review its pull requests in Hamster.
The Bitbucket Connection gives Hamster two things at once:
One Bitbucket Connection covers every repository the Atlassian account you sign in with can see, across all of its Bitbucket workspaces. You add another Bitbucket Connection only if you need to bring in a second Atlassian account.
Bitbucket Cloud (bitbucket.org) only. Bitbucket Data Center and Server are not supported.
Each repository tracks one branch, which you choose when you connect it.
Once a repository is indexed, ask about it in Chat and Hamster answers from that code.
After you confirm your first selection, Hamster shows Bitbucket is Connected.
On the Hamster Free plan, if your workspace already has a repository connected, clicking the Bitbucket Repos tile opens an upgrade prompt instead of the Bitbucket dialog.
If you deny access on Bitbucket, or authorization fails, Hamster shows "Couldn't connect to Bitbucket. Please try again." Start again from the Bitbucket Repos tile.
When Hamster needs your code in a conversation, it shows a Connect your code card in chat with a Bitbucket button, the same card your Getting started chat offers.
For each repository you select, choose the branch to track — by default the repository's main branch on Bitbucket. Hamster indexes code from that branch.
Confirming the selection starts indexing each repository. Repositories you clear from the selection stop syncing and drop out of code search, without affecting the Connection itself.
Only members who can manage connections see the Bitbucket Repos tile or can open a connected card's picker.
If the Atlassian account can see too many repositories (about 5,000, or fewer when they're spread across many workspaces), the picker shows Couldn't load repositories with the message connection_repository_list_too_large. Connect with an account that belongs to fewer workspaces or repositories, such as a dedicated account added only to the repositories Hamster needs.
Code updates normally appear after a push to the tracked branch. Hamster adds a webhook named Hamster to each repository you select so Bitbucket can tell Hamster about changes. Pushes to other branches don't update the index.
Adding a webhook needs Admin permission on the repository. If the account that authorized the Connection isn't an admin on a repository, Hamster still indexes it but can't add its webhook. Updates then take longer to appear, the repository's activity can't start Routines, and Review picks up pull request changes when you open it rather than live.
The connected Bitbucket card shows how many repositories are connected and a rollup of indexing state across them: Indexing, Embedding, Indexed, Index stale, or Sync failed. Hover over Sync failed to see why.
Index stale means Hamster hasn't confirmed recently that the repository is up to date. Hamster checks again automatically. Hover over Indexed on the card to see when Hamster last indexed this connection.
If the connected Bitbucket card shows Reconnect to continue syncing, click it and reconnect Bitbucket. Grant access as the Atlassian account you first connected with, and Hamster keeps your repository selections. If you grant access as a different account, Hamster adds a second Bitbucket card, and the first one still needs reconnecting. If you can't manage connections, the card reads Ask an admin or creator on this account to reconnect instead.
Click the connected Bitbucket card to reopen the repository picker. There is nothing to install or configure on Bitbucket's side; you choose which repositories Hamster uses from this picker.
To stop indexing a repository, clear it from the selection and confirm. If you clear every repository, the button reads Stop indexing repositories. Confirming stops indexing all of them and keeps the Connection. To change which branch a repository tracks, reopen the picker and choose a different one.
To remove the connection, hover over the connected Bitbucket card, click ×, then click Delete. You need permission to manage connections. Hamster stops indexing every repository from that Atlassian account and removes the indexed code.
Hamster also deletes the webhooks it added to your repositories. Removing the connection doesn't revoke Hamster's access on Bitbucket; revoke it from your Bitbucket personal settings. If Hamster's access had already expired or was revoked, Hamster can't delete the webhooks, so delete the Hamster webhook yourself from each repository's settings on Bitbucket.
If you rename a repository or move it to another workspace, you don't need to reconnect it.
Link a Bitbucket pull request to a Brief to review it in Hamster: select its repository in the Bitbucket picker, then follow Link a Pull Request by Hand. If Bitbucket isn't connected, Hamster says "Connect Bitbucket Repos so Hamster can link this pull request." If it is but the repository isn't selected, Hamster says the repository isn't connected to your team. In the Brief header, the pull request control shows Draft, Open, Merged, or Closed and links out to Bitbucket. A declined pull request shows Closed.
Review shows a guided Tour of a Bitbucket pull request, with file diffs, comment threads, and each participant's approval. Updates arrive from Bitbucket as they happen. A pull request opening, new comments, approvals, requests for changes, and a merged or declined pull request each post a line to the Brief's thread.
Sign in with Bitbucket so your comments and decisions post as you instead of staying in Hamster. Until you do, Review says "Comments and approvals stay in Hamster until you sign in." Click Sign in with Bitbucket. If your sign-in expires, Review says "Bitbucket sign-in expired. Reconnect to post comments and approvals as yourself." Click Reconnect Bitbucket.
Signing in from Review connects your own Atlassian account, so it also adds a Bitbucket card under Connections. That card indexes nothing until someone selects repositories in it. Each Atlassian account can be linked to only one Hamster user.
Bitbucket doesn't let anyone approve their own pull request, so Ready is off on a pull request you opened. Anyone else on the team can approve it, as long as their Atlassian account can see the repository.
Review doesn't show Bitbucket build statuses. Check them on Bitbucket.
Activity on a connected Bitbucket repository can start a Routine. Bitbucket uses the GitHub triggers in the trigger picker, and connected repositories appear in their Repository list. If nothing is connected, that list reads "No GitHub repositories connected." On Bitbucket, the triggers fire like this:
From the Skills tab, click New skill and select Sync repo skills, then pick your Bitbucket repository. Hamster reads the SKILL.md files in its .agents/skills/, .claude/skills/, or skills/ folder from the last indexed snapshot and adds them to your Skills library.
The repository must finish its first index before you can import from it. If nothing is connected yet, the dialog says Connect GitHub to import skills and offers Connect GitHub. Connect your repository from the Bitbucket Repos tile instead.
Import from GitHub only takes public GitHub links, so it can't read a Bitbucket repository.
main or develop, not a feature branch.