Bitbucket

The @guildai-services/guildai~bitbucket package provides agents with access to the Bitbucket Cloud REST API through Guild’s OAuth 2.0 integration.

Authentication

Type: OAuth 2.0
Token expiration: 1 hour (auto-refreshed)
Note: Only Bitbucket Cloud is supported — not Bitbucket Server or Data Center

Setup

Open Credentials

Go to Credentials in Guild.

Connect Bitbucket

Click Bitbucket and authorize Guild to access your account.

Grant access

Select the workspaces and repositories to authorize.

Usage

import { bitbucketTools } from "@guildai-services/guildai~bitbucket"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Bitbucket pull requests",
  tools: { ...bitbucketTools },
})

Selecting specific tools

Agents perform better with fewer tools. Use pick() to include only what your agent needs. Tools are named with the bitbucket_ prefix.

import { bitbucketTools } from "@guildai-services/guildai~bitbucket"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Bitbucket pull requests",
  tools: {
    ...pick(bitbucketTools, [
      "bitbucket_get_repositories_workspace_repo_slug_pullrequests",
      "bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id",
      "bitbucket_post_repositories_workspace_repo_slug_pullrequests",
      "bitbucket_post_repositories_workspace_repo_slug_pullrequests_pull_request_id_merge",
    ]),
  },
})

API endpoints

Workspaces

Operation	Method	Path
`get_workspaces`	GET	`/workspaces`
`get_workspaces_workspace`	GET	`/workspaces/{workspace}`
`get_workspaces_workspace_members`	GET	`/workspaces/{workspace}/members`
`get_workspaces_workspace_projects`	GET	`/workspaces/{workspace}/projects`
`post_workspaces_workspace_projects`	POST	`/workspaces/{workspace}/projects`

Repositories

Operation	Method	Path
`get_repositories_workspace`	GET	`/repositories/{workspace}`
`get_repositories_workspace_repo_slug`	GET	`/repositories/{workspace}/{repo_slug}`
`post_repositories_workspace_repo_slug`	POST	`/repositories/{workspace}/{repo_slug}`
`put_repositories_workspace_repo_slug`	PUT	`/repositories/{workspace}/{repo_slug}`
`delete_repositories_workspace_repo_slug`	DELETE	`/repositories/{workspace}/{repo_slug}`

Branches

Operation	Method	Path
`get_repositories_workspace_repo_slug_refs_branches`	GET	`/repositories/{workspace}/{repo_slug}/refs/branches`
`post_repositories_workspace_repo_slug_refs_branches`	POST	`/repositories/{workspace}/{repo_slug}/refs/branches`
`get_repositories_workspace_repo_slug_refs_branches_name`	GET	`/repositories/{workspace}/{repo_slug}/refs/branches/{name}`
`delete_repositories_workspace_repo_slug_refs_branches_name`	DELETE	`/repositories/{workspace}/{repo_slug}/refs/branches/{name}`

Commits

Operation	Method	Path
`get_repositories_workspace_repo_slug_commits`	GET	`/repositories/{workspace}/{repo_slug}/commits`
`get_repositories_workspace_repo_slug_commit_commit`	GET	`/repositories/{workspace}/{repo_slug}/commit/{commit}`
`get_repositories_workspace_repo_slug_commit_commit_statuses`	GET	`/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses`
`get_repositories_workspace_repo_slug_commit_commit_comments`	GET	`/repositories/{workspace}/{repo_slug}/commit/{commit}/comments`
`post_repositories_workspace_repo_slug_commit_commit_comments`	POST	`/repositories/{workspace}/{repo_slug}/commit/{commit}/comments`

Pull requests

Operation	Method	Path
`get_repositories_workspace_repo_slug_pullrequests`	GET	`/repositories/{workspace}/{repo_slug}/pullrequests`
`post_repositories_workspace_repo_slug_pullrequests`	POST	`/repositories/{workspace}/{repo_slug}/pullrequests`
`get_repositories_workspace_repo_slug_pullrequests_pull_request_id`	GET	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}`
`put_repositories_workspace_repo_slug_pullrequests_pull_request_id`	PUT	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}`
`post_repositories_workspace_repo_slug_pullrequests_pull_request_id_approve`	POST	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/approve`
`post_repositories_workspace_repo_slug_pullrequests_pull_request_id_merge`	POST	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge`
`post_repositories_workspace_repo_slug_pullrequests_pull_request_id_decline`	POST	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/decline`
`get_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments`	GET	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments`
`post_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments`	POST	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments`
`get_repositories_workspace_repo_slug_pullrequests_pull_request_id_commits`	GET	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/commits`
`get_repositories_workspace_repo_slug_pullrequests_pull_request_id_diff`	GET	`/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/diff`

Issues

Operation	Method	Path
`get_repositories_workspace_repo_slug_issues`	GET	`/repositories/{workspace}/{repo_slug}/issues`
`post_repositories_workspace_repo_slug_issues`	POST	`/repositories/{workspace}/{repo_slug}/issues`
`get_repositories_workspace_repo_slug_issues_issue_id`	GET	`/repositories/{workspace}/{repo_slug}/issues/{issue_id}`
`put_repositories_workspace_repo_slug_issues_issue_id`	PUT	`/repositories/{workspace}/{repo_slug}/issues/{issue_id}`
`delete_repositories_workspace_repo_slug_issues_issue_id`	DELETE	`/repositories/{workspace}/{repo_slug}/issues/{issue_id}`
`get_repositories_workspace_repo_slug_issues_issue_id_comments`	GET	`/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments`
`post_repositories_workspace_repo_slug_issues_issue_id_comments`	POST	`/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments`

Source & diffs

Operation	Method	Path
`get_repositories_workspace_repo_slug_src`	GET	`/repositories/{workspace}/{repo_slug}/src`
`get_repositories_workspace_repo_slug_src_commit_path`	GET	`/repositories/{workspace}/{repo_slug}/src/{commit}/{path}`
`get_repositories_workspace_repo_slug_diff_spec`	GET	`/repositories/{workspace}/{repo_slug}/diff/{spec}`
`get_repositories_workspace_repo_slug_diffstat_spec`	GET	`/repositories/{workspace}/{repo_slug}/diffstat/{spec}`

Webhook events

Bitbucket uses a trigger-scoped webhook model — each trigger gets its own dedicated webhook with a unique secret.

Event	Description
`issue:created`	Issue created
`issue:updated`	Issue updated
`pullrequest:created`	Pull request created
`pullrequest:updated`	Pull request updated
`pullrequest:approved`	Pull request approved
`pullrequest:fulfilled`	Pull request merged
`pullrequest:rejected`	Pull request declined
`pullrequest:comment_created`	Comment created on a pull request
`repo:push`	Commits pushed to a repository
`repo:commit_status_created`	Commit status created
`repo:commit_status_updated`	Commit status updated

Triggers require a workspace_slug and optionally a repo_slug to scope webhooks to a specific workspace or repository.

Package version

The @guildai-services/guildai~bitbucket package is on the 2.x release line. The 2.x package is a code-generated client built directly from Bitbucket’s OpenAPI specification, replacing the hand-maintained 1.x package. If you are migrating an agent that was written against the 1.x package, review your tool names — some operation identifiers changed between versions. All operations follow the same bitbucket_<method>_<path> naming convention as before, but paths may have been normalized.

Limitations

Only Bitbucket Cloud is supported (not Bitbucket Server or Data Center)
Each trigger creates a separate webhook on the repository

Overview

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Authentication

Setup

Usage

Selecting specific tools

API endpoints

Webhook events

Package version

Limitations

​Authentication

​Setup

​Usage

​Selecting specific tools

​API endpoints

​Webhook events

​Package version

​Limitations

Authentication

Setup

Usage

Selecting specific tools

API endpoints

Webhook events

Package version

Limitations