Manage Bitbucket pull requests and issues from Guild agents

Integrations · Bitbucket

Guild agents read, create, approve, and merge Bitbucket pull requests, manage issues, and act on repository events without storing credentials in agent code. Guild’s credential proxy injects the OAuth token server-side and enforces credential policies before any request reaches Bitbucket. Every action is captured in Guild’s audit trail.

Book a demo

See how teams govern agents that use Bitbucket.

Start free

Connect Bitbucket and scope your first agent.

What the Bitbucket integration exposes

The tools cover repositories, branches, commits, pull requests, issues, webhooks, and workspaces on Bitbucket Cloud. Agents can list and inspect resources, create and update them, approve or merge pull requests, manage branch restrictions and default reviewers, and read file contents and diffs. Three webhook events let triggers fire agents when a pull request, issue, or repository push occurs.

How it works

Open Credentials in Guild

Go to Credentials in Guild. The page lists connected services and a gallery of available integrations.

Authorize Bitbucket via OAuth

Click Bitbucket and complete the OAuth 2.0 flow. Select the workspaces and repositories to authorize. Tokens expire after one hour and are refreshed automatically.

Add tools to your agent

Import bitbucketTools from @guildai-services/guildai~bitbucket and spread it into your agent’s tools object. Use pick() to include only the tools your agent needs, since agents perform better with fewer tools.

Why Bitbucket access needs governing

Bitbucket tools can create repositories, delete branches, merge pull requests, and modify branch restriction rules. A credential without policies grants an agent everything the connected Bitbucket account can reach. Guild’s credential policies let you write ALLOW and DENY rules that the credential proxy enforces before any request leaves Guild, limiting agents by operation, resource, workspace, or agent identity. Guild stores OAuth tokens server-side and injects them into requests through the credential proxy; agent code never sees the token. You can scope a credential to one workspace, one member, or one agent, and restrict a workspace so it ignores account-level credentials entirely. See credentials for scoping options and credential policies for rule syntax. Without policies, every agent that resolves the credential can use it without restriction.

About the Bitbucket integration

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.

To connect with a Bitbucket workspace access token instead of OAuth, use the guildai~bitbucket-token integration. Create the token in Bitbucket under Workspace settings > Security > Access tokens, and paste it into API Key. Give the token the webhook read and write scope so triggers can register their webhooks. It supports the same trigger events; the package and tools on this page are for the OAuth integration.

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",
    ]),
  },
})

Tools

Tools in the latest published version of guildai~bitbucket:

All 93 tools

Tool	What it does
`bitbucket_delete_repositories_workspace_repo_slug`	Deletes the repository.
`bitbucket_delete_repositories_workspace_repo_slug_branch_restrictions_id`	Deletes an existing branch restriction rule.
`bitbucket_delete_repositories_workspace_repo_slug_commit_commit_comments_comment_id`	Deletes the specified commit comment.
`bitbucket_delete_repositories_workspace_repo_slug_default_reviewers_target_username`	Removes a default reviewer from the repository.
`bitbucket_delete_repositories_workspace_repo_slug_hooks_uid`	Deletes the specified webhook subscription from the given repository.
`bitbucket_delete_repositories_workspace_repo_slug_issues_issue_id`	Deletes the specified issue.
`bitbucket_delete_repositories_workspace_repo_slug_issues_issue_id_attachments_path`	Deletes an attachment.
`bitbucket_delete_repositories_workspace_repo_slug_issues_issue_id_comments_comment_id`	Deletes the specified comment.
`bitbucket_delete_repositories_workspace_repo_slug_issues_issue_id_vote`	Retract your vote.
`bitbucket_delete_repositories_workspace_repo_slug_issues_issue_id_watch`	Stop watching this issue.
`bitbucket_delete_repositories_workspace_repo_slug_pullrequests_pull_request_id_approve`	Redact the authenticated user’s approval of the specified pull request.
`bitbucket_delete_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments_comment_id`	Deletes a specific pull request comment.
`bitbucket_delete_repositories_workspace_repo_slug_pullrequests_pull_request_id_request_changes`	Delete repositories workspace repo slug pullrequests pull request id request changes.
`bitbucket_delete_repositories_workspace_repo_slug_refs_branches_name`	Delete a branch in the specified repository.
`bitbucket_delete_workspaces_workspace_projects_project_key`	Deletes this project.
`bitbucket_get_repositories_workspace`	Returns a paginated list of all repositories owned by the specified workspace.
`bitbucket_get_repositories_workspace_repo_slug`	Returns the object describing this repository.
`bitbucket_get_repositories_workspace_repo_slug_branching_model`	Return the branching model as applied to the repository.
`bitbucket_get_repositories_workspace_repo_slug_branching_model_settings`	Return the branching model configuration for a repository.
`bitbucket_get_repositories_workspace_repo_slug_branch_restrictions`	Returns a paginated list of all branch restrictions on the repository.
`bitbucket_get_repositories_workspace_repo_slug_branch_restrictions_id`	Returns a specific branch restriction rule.
`bitbucket_get_repositories_workspace_repo_slug_commit_commit`	Returns the specified commit.
`bitbucket_get_repositories_workspace_repo_slug_commit_commit_comments`	Returns the commit’s comments.
`bitbucket_get_repositories_workspace_repo_slug_commit_commit_comments_comment_id`	Returns the specified commit comment.
`bitbucket_get_repositories_workspace_repo_slug_commit_commit_statuses`	Returns all statuses (e.g. build results) for a specific commit.
`bitbucket_get_repositories_workspace_repo_slug_commits`	These are the repository’s commits.
`bitbucket_get_repositories_workspace_repo_slug_commits_revision`	These are the repository’s commits.
`bitbucket_get_repositories_workspace_repo_slug_default_reviewers`	Returns the repository’s default reviewers.
`bitbucket_get_repositories_workspace_repo_slug_default_reviewers_target_username`	Returns the specified reviewer.
`bitbucket_get_repositories_workspace_repo_slug_diff_spec`	Produces a raw git-style diff.
`bitbucket_get_repositories_workspace_repo_slug_diffstat_spec`	Produces a response in JSON format with a record for every path modified, including information on the type of the change and the number of lines added and removed.
`bitbucket_get_repositories_workspace_repo_slug_filehistory_commit_path`	Returns a paginated list of commits that modified the specified file.
`bitbucket_get_repositories_workspace_repo_slug_hooks`	Returns a paginated list of webhooks installed on this repository.
`bitbucket_get_repositories_workspace_repo_slug_hooks_uid`	Returns the webhook with the specified id installed on the specified repository.
`bitbucket_get_repositories_workspace_repo_slug_issues`	Returns the issues in the issue tracker.
`bitbucket_get_repositories_workspace_repo_slug_issues_issue_id`	Returns the specified issue.
`bitbucket_get_repositories_workspace_repo_slug_issues_issue_id_attachments`	Returns all attachments for this issue.
`bitbucket_get_repositories_workspace_repo_slug_issues_issue_id_attachments_path`	Returns the contents of the specified file attachment.
`bitbucket_get_repositories_workspace_repo_slug_issues_issue_id_comments`	Returns a paginated list of all comments that were made on the specified issue.
`bitbucket_get_repositories_workspace_repo_slug_issues_issue_id_comments_comment_id`	Returns the specified issue comment object.
`bitbucket_get_repositories_workspace_repo_slug_issues_issue_id_vote`	Check whether the authenticated user has voted for this issue.
`bitbucket_get_repositories_workspace_repo_slug_issues_issue_id_watch`	Indicated whether or not the authenticated user is watching this issue.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests`	Returns all pull requests on the specified repository.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_activity`	Returns a paginated list of the pull request’s activity log.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id`	Returns the specified pull request.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id_activity`	Returns a paginated list of the pull request’s activity log.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments`	Returns a paginated list of the pull request’s comments.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments_comment_id`	Returns a specific pull request comment.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id_commits`	Returns a paginated list of the pull request’s commits.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id_diff`	Redirects to the repository diff with the revspec that corresponds to the pull request.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id_diffstat`	Redirects to the repository diffstat with the revspec that corresponds to the pull request.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id_patch`	Redirects to the repository patch with the revspec that corresponds to pull request.
`bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id_statuses`	Returns all statuses (e.g. build results) for the given pull request.
`bitbucket_get_repositories_workspace_repo_slug_refs_branches`	Returns a list of all open branches within the specified repository.
`bitbucket_get_repositories_workspace_repo_slug_refs_branches_name`	Returns a branch object within the specified repository.
`bitbucket_get_repositories_workspace_repo_slug_src`	This endpoint redirects the client to the directory listing of the root directory on the main branch.
`bitbucket_get_repositories_workspace_repo_slug_src_commit_path`	This endpoints is used to retrieve the contents of a single file, or the contents of a directory at a specified revision.
`bitbucket_get_user_workspaces`	Get user workspaces.
`bitbucket_get_workspaces_workspace`	Returns the requested workspace.
`bitbucket_get_workspaces_workspace_members`	Returns all members of the requested workspace.
`bitbucket_get_workspaces_workspace_projects`	Returns the list of projects in this workspace.
`bitbucket_get_workspaces_workspace_projects_project_key`	Returns the requested project.
`bitbucket_post_repositories_workspace_repo_slug`	Creates a new repository.
`bitbucket_post_repositories_workspace_repo_slug_branch_restrictions`	Creates a new branch restriction rule for a repository.
`bitbucket_post_repositories_workspace_repo_slug_commit_commit_comments`	Creates new comment on the specified commit.
`bitbucket_post_repositories_workspace_repo_slug_commits`	Identical to `GET /repositories/{workspace}/{repo_slug}/commits`, except that POST allows clients to place the include and exclude parameters in the request body to avoid URL length issues.
`bitbucket_post_repositories_workspace_repo_slug_commits_revision`	Identical to `GET /repositories/{workspace}/{repo_slug}/commits/{revision}`, except that POST allows clients to place the include and exclude parameters in the request body to avoid URL length issues.
`bitbucket_post_repositories_workspace_repo_slug_hooks`	Creates a new webhook on the specified repository.
`bitbucket_post_repositories_workspace_repo_slug_issues`	Creates a new issue.
`bitbucket_post_repositories_workspace_repo_slug_issues_issue_id_attachments`	Upload new issue attachments.
`bitbucket_post_repositories_workspace_repo_slug_issues_issue_id_comments`	Creates a new issue comment.
`bitbucket_post_repositories_workspace_repo_slug_pullrequests`	Creates a new pull request where the destination repository is this repository and the author is the authenticated user.
`bitbucket_post_repositories_workspace_repo_slug_pullrequests_pull_request_id_approve`	Approve the specified pull request as the authenticated user.
`bitbucket_post_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments`	Creates a new pull request comment.
`bitbucket_post_repositories_workspace_repo_slug_pullrequests_pull_request_id_decline`	Declines the pull request.
`bitbucket_post_repositories_workspace_repo_slug_pullrequests_pull_request_id_merge`	Merges the pull request.
`bitbucket_post_repositories_workspace_repo_slug_pullrequests_pull_request_id_request_changes`	Post repositories workspace repo slug pullrequests pull request id request changes.
`bitbucket_post_repositories_workspace_repo_slug_refs_branches`	Creates a new branch in the specified repository.
`bitbucket_post_repositories_workspace_repo_slug_src`	This endpoint is used to create new commits in the repository by uploading files.
`bitbucket_post_workspaces_workspace_projects`	Creates a new project.
`bitbucket_put_repositories_workspace_repo_slug`	Since this endpoint can be used to both update and to create a repository, the request body depends on the intent.
`bitbucket_put_repositories_workspace_repo_slug_branching_model_settings`	Update the branching model configuration for a repository.
`bitbucket_put_repositories_workspace_repo_slug_branch_restrictions_id`	Updates an existing branch restriction rule.
`bitbucket_put_repositories_workspace_repo_slug_commit_commit_comments_comment_id`	Used to update the contents of a comment.
`bitbucket_put_repositories_workspace_repo_slug_default_reviewers_target_username`	Adds the specified user to the repository’s list of default reviewers.
`bitbucket_put_repositories_workspace_repo_slug_hooks_uid`	Updates the specified webhook subscription.
`bitbucket_put_repositories_workspace_repo_slug_issues_issue_id`	Modifies the issue.
`bitbucket_put_repositories_workspace_repo_slug_issues_issue_id_comments_comment_id`	Updates the content of the specified issue comment.
`bitbucket_put_repositories_workspace_repo_slug_issues_issue_id_vote`	Vote for this issue.
`bitbucket_put_repositories_workspace_repo_slug_issues_issue_id_watch`	Start watching this issue.
`bitbucket_put_repositories_workspace_repo_slug_pullrequests_pull_request_id`	Mutates the specified pull request.
`bitbucket_put_repositories_workspace_repo_slug_pullrequests_pull_request_id_comments_comment_id`	Updates a specific pull request comment.
`bitbucket_put_workspaces_workspace_projects_project_key`	Since this endpoint can be used to both update and to create a project, the request body depends on the intent.

Webhook events

Bitbucket uses a trigger-scoped webhook model — each trigger gets its own webhook with a unique secret, subscribed to the trigger’s event and action, or to every event when the trigger names none. Guild checks each delivery’s X-Hub-Signature. A trigger can narrow an event to one action, such as --event pullrequest --action created. Without an action it fires on every action of that event.

Event	Description	Actions
`issue`	Issue created or updated, or comment added	`comment_created`, `created`, `updated`
`pullrequest`	Pull request created, updated, approved, merged, declined, or commented on	`approved`, `comment_created`, `comment_deleted`, `comment_updated`, `created`, `fulfilled`, `rejected`, `unapproved`, `updated`
`repo`	Commits pushed to a repository	`push`

Every trigger needs a workspace_slug in its service config. Add a repo_slug to install the webhook on one repository; without it, the webhook is installed on the workspace, where Bitbucket supports the event.

{
  "workspace_slug": "myworkspace",
  "repo_slug": "myrepo"
}

Each event starts a new session. Guild doesn’t filter out changes the agent makes itself, so an agent that comments on a pull request from a pullrequest comment_created trigger fires that trigger again. Have the agent skip comments by the connected account.

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 or workspace

Frequently asked questions

Does this integration work with Bitbucket Server or Data Center?

No. Only Bitbucket Cloud is supported. Bitbucket Server and Data Center are not supported by this integration.

Can I trigger an agent only when a pull request is created, not on every pull request event?

Yes. A trigger can narrow the pullrequest event to one action, such as --event pullrequest --action created. Without an action specified, the trigger fires on every action of that event, including approved, merged, declined, and commented.

How do I limit which repositories an agent can touch?

Write a credential policy with ALLOW or DENY rules scoped to specific operations and agents. Guild’s credential proxy enforces the policy before any request reaches Bitbucket, so an agent cannot reach repositories the policy does not permit. See credential policies for rule syntax.

Can I connect with a workspace access token instead of OAuth?

Yes. Use the guildai~bitbucket-token integration instead. Create a token in Bitbucket under Workspace settings > Security > Access tokens, give it webhook read and write scope, and paste it into the API Key field. It supports the same trigger events as the OAuth integration.

Put a governed agent on Bitbucket this week

Book a demo

See how teams govern agents that use Bitbucket.

Start free

Connect Bitbucket and scope your first agent.

Also runs on Guild: Azure DevOps · GitHub · Google Compute · Linear Read: Docs: Credential policies · Credentials · Tools in agents

Overview

Models

Inference providers

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Recruiting

Manage Bitbucket pull requests and issues from Guild agents

Book a demo

Start free

What the Bitbucket integration exposes

How it works

Why Bitbucket access needs governing

About the Bitbucket integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Webhook events

Package version

Limitations

Frequently asked questions

Put a governed agent on Bitbucket this week

Book a demo

Start free

Book a demo

Start free

​What the Bitbucket integration exposes

​How it works

​Why Bitbucket access needs governing

​About the Bitbucket integration

​Authentication

​Setup

​Usage

​Selecting specific tools

​Tools

​Webhook events

​Package version

​Limitations

​Frequently asked questions

​Put a governed agent on Bitbucket this week

Book a demo

Start free

​Related

What the Bitbucket integration exposes

How it works

Why Bitbucket access needs governing

About the Bitbucket integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Webhook events

Package version

Limitations

Frequently asked questions

Put a governed agent on Bitbucket this week

Related