Bitbucket Toolkit
The Bitbucket toolkit lets agents work with Bitbucket Cloud: list workspaces and repositories, read file content, list branches and commits, and manage pull requests and issues. Authentication is per-user OAuth — each user connects their own Bitbucket account.
Add it on the agent Toolkits tab. The first use prompts the user to connect Bitbucket if they have not already.
Prerequisites
- Bitbucket Cloud access to the workspaces and repos the agent should use
- An agent you can edit
- Users who will chat with the agent must complete the Bitbucket OAuth connect flow when prompted
Setup
- Open the agent → Toolkits → add Bitbucket.
- Optionally set a default workspace in toolkit config (tools still accept an explicit workspace when needed).
- Save the agent. In Chat, connect Bitbucket when prompted (or via the authenticate tool).
@-mention Bitbucket tools in the personality prompt for repo, PR, or issue tasks.
Available tools
| Tool | Description |
|---|---|
| Get Workspaces | Lists Bitbucket workspaces the authenticated user can access. |
| List Repositories | Lists repositories, with optional workspace, role filter, sort, and pagination. |
| Get Repository | Returns repository details (language, default branch, clone/HTML URLs, and more). |
| Search Repositories | Searches repositories across accessible workspaces. |
| Get File Content | Reads a file from a repo at a branch or commit (uses the default branch when ref is omitted). |
| List Branches | Lists branches with commit metadata. |
| List Pull Requests | Lists PRs filtered by state (OPEN, MERGED, DECLINED, SUPERSEDED). |
| Get Pull Request | Returns PR details, including diff and comments. |
| Create Pull Request | Creates a PR from a source branch to a destination branch. |
| List Issues | Lists repository issues, with optional state filter. |
| Create Issue | Creates an issue (title, optional content, kind, priority). |
| Get Commit History | Lists commits for a repository/branch with pagination. |
When the user is not connected, the agent can offer Authenticate Bitbucket to start the OAuth flow.
Use cases
- Summarize open pull requests or recent commits for a repository
- Read a config or README file from a branch during troubleshooting
- Open a PR after documenting a change, or file a bug issue from chat
- Discover which workspaces and repos the signed-in user can access
Tips
- Access is limited to what the connected Bitbucket user can see — not a shared service account unless that account connects.
- List tools paginate with a page size capped at 100 (default is smaller).
- Creating PRs and issues needs sufficient Bitbucket write permissions on the repo.
- Prefer an explicit workspace and repo slug when names collide.
- For GitHub or GitLab, use those toolkits instead (GitHub, GitLab).
Troubleshooting
| Symptom | What to check |
|---|---|
| Authenticate / connect loop | Complete the Bitbucket OAuth prompt with the correct account; try disconnecting and connecting again |
| Empty workspace or repo list | The connected user lacks access; reconnect with the correct Bitbucket account |
| Cannot create PR or issue | Bitbucket write permissions on the repository for the connected user |
| Get File Content fails | Confirm workspace, repo slug, path, and branch/ref |
| Timeouts on large files | Prefer smaller files or a specific path; large blobs may hit API or timeout limits |