Skip to main content
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

1

Open Credentials

Go to Credentials in Guild.
2

Connect Bitbucket

Click Bitbucket and authorize Guild to access your account.
3

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

OperationMethodPath
get_workspacesGET/workspaces
get_workspaces_workspaceGET/workspaces/{workspace}
get_workspaces_workspace_membersGET/workspaces/{workspace}/members
get_workspaces_workspace_projectsGET/workspaces/{workspace}/projects
post_workspaces_workspace_projectsPOST/workspaces/{workspace}/projects
OperationMethodPath
get_repositories_workspaceGET/repositories/{workspace}
get_repositories_workspace_repo_slugGET/repositories/{workspace}/{repo_slug}
post_repositories_workspace_repo_slugPOST/repositories/{workspace}/{repo_slug}
put_repositories_workspace_repo_slugPUT/repositories/{workspace}/{repo_slug}
delete_repositories_workspace_repo_slugDELETE/repositories/{workspace}/{repo_slug}
OperationMethodPath
get_repositories_workspace_repo_slug_refs_branchesGET/repositories/{workspace}/{repo_slug}/refs/branches
post_repositories_workspace_repo_slug_refs_branchesPOST/repositories/{workspace}/{repo_slug}/refs/branches
get_repositories_workspace_repo_slug_refs_branches_nameGET/repositories/{workspace}/{repo_slug}/refs/branches/{name}
delete_repositories_workspace_repo_slug_refs_branches_nameDELETE/repositories/{workspace}/{repo_slug}/refs/branches/{name}
OperationMethodPath
get_repositories_workspace_repo_slug_commitsGET/repositories/{workspace}/{repo_slug}/commits
get_repositories_workspace_repo_slug_commit_commitGET/repositories/{workspace}/{repo_slug}/commit/{commit}
get_repositories_workspace_repo_slug_commit_commit_statusesGET/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses
get_repositories_workspace_repo_slug_commit_commit_commentsGET/repositories/{workspace}/{repo_slug}/commit/{commit}/comments
post_repositories_workspace_repo_slug_commit_commit_commentsPOST/repositories/{workspace}/{repo_slug}/commit/{commit}/comments
OperationMethodPath
get_repositories_workspace_repo_slug_pullrequestsGET/repositories/{workspace}/{repo_slug}/pullrequests
post_repositories_workspace_repo_slug_pullrequestsPOST/repositories/{workspace}/{repo_slug}/pullrequests
get_repositories_workspace_repo_slug_pullrequests_pull_request_idGET/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}
put_repositories_workspace_repo_slug_pullrequests_pull_request_idPUT/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}
post_repositories_workspace_repo_slug_pullrequests_pull_request_id_approvePOST/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/approve
post_repositories_workspace_repo_slug_pullrequests_pull_request_id_mergePOST/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge
post_repositories_workspace_repo_slug_pullrequests_pull_request_id_declinePOST/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/decline
get_repositories_workspace_repo_slug_pullrequests_pull_request_id_commentsGET/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments
post_repositories_workspace_repo_slug_pullrequests_pull_request_id_commentsPOST/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments
get_repositories_workspace_repo_slug_pullrequests_pull_request_id_commitsGET/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/commits
get_repositories_workspace_repo_slug_pullrequests_pull_request_id_diffGET/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/diff
OperationMethodPath
get_repositories_workspace_repo_slug_issuesGET/repositories/{workspace}/{repo_slug}/issues
post_repositories_workspace_repo_slug_issuesPOST/repositories/{workspace}/{repo_slug}/issues
get_repositories_workspace_repo_slug_issues_issue_idGET/repositories/{workspace}/{repo_slug}/issues/{issue_id}
put_repositories_workspace_repo_slug_issues_issue_idPUT/repositories/{workspace}/{repo_slug}/issues/{issue_id}
delete_repositories_workspace_repo_slug_issues_issue_idDELETE/repositories/{workspace}/{repo_slug}/issues/{issue_id}
get_repositories_workspace_repo_slug_issues_issue_id_commentsGET/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments
post_repositories_workspace_repo_slug_issues_issue_id_commentsPOST/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments
OperationMethodPath
get_repositories_workspace_repo_slug_srcGET/repositories/{workspace}/{repo_slug}/src
get_repositories_workspace_repo_slug_src_commit_pathGET/repositories/{workspace}/{repo_slug}/src/{commit}/{path}
get_repositories_workspace_repo_slug_diff_specGET/repositories/{workspace}/{repo_slug}/diff/{spec}
get_repositories_workspace_repo_slug_diffstat_specGET/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.
EventDescription
issue:createdIssue created
issue:updatedIssue updated
pullrequest:createdPull request created
pullrequest:updatedPull request updated
pullrequest:approvedPull request approved
pullrequest:fulfilledPull request merged
pullrequest:rejectedPull request declined
pullrequest:comment_createdComment created on a pull request
repo:pushCommits pushed to a repository
repo:commit_status_createdCommit status created
repo:commit_status_updatedCommit status updated
Triggers require a workspace_slug and optionally a repo_slug to scope webhooks to a specific workspace or repository.

​
Limitations

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