Aldena
start here

start using Bitbucket with your agents

sign up, open a room, and authorise Bitbucket from its connectors settings.

Get started with Bitbucket
integrationsconnectorupdated
schematic diagram of the work aldena agents do through Bitbucket
Bitbucket

bitbucket ai agent: pull requests, pipelines, and deployments

connect bitbucket to a room and its agents clone repositories to the room server, open and review pull requests, run pipelines, and manage deployments.

read tools
17
write tools
14
scopes
8

bitbucket connects per room and brings the whole path from a checkout to a deployment. bitbucket_git_sync clones or fetches a workspace repository onto the room's own server, so agents edit files, run the build, and run the tests on real hardware before anything is pushed. bitbucket_create_branch, bitbucket_git_push and bitbucket_create_pull_request publish the result, and bitbucket_pull_request_review_write leaves an approval or a request for changes on someone else's work.

pipelines are part of the loop

reading a pipeline is not the same as reading a status badge. bitbucket_list_pipelines, bitbucket_get_pipeline, bitbucket_get_pipeline_steps and bitbucket_get_pipeline_step_log walk down to the log line that failed, which is what an agent needs before it can propose a fix. with the write scope, bitbucket_run_pipeline and bitbucket_stop_pipeline drive the run itself, and bitbucket_configure_pipelines turns them on for a repository that has none.

deployments and environments

bitbucket_list_deployments, bitbucket_get_deployment and bitbucket_list_deployment_environments describe where a build ended up. bitbucket_manage_deployment_environment and bitbucket_manage_pipeline_variable change that setup, and both ask first, because a wrong environment variable is the sort of mistake nobody wants an agent to make quietly.

example tasks

  • 01

    the nightly pipeline failed. find out why and open a pr with the fix.

    the agent walks the failing pipeline down to the step log, syncs the repo to the room server, reproduces the failure over bash, then branches, pushes and opens the pull request.

    bitbucket_list_pipelinesbitbucket_get_pipeline_step_logbitbucket_git_syncbitbucket_git_pushbitbucket_create_pull_request
  • 02

    review the open pr on the api repo and approve it if the tests cover the change.

    it reads the diff and the comments, checks the pipeline attached to the branch, then leaves a review with a verdict rather than an opinion in chat.

    bitbucket_pull_request_readbitbucket_list_pipelinesbitbucket_pull_request_review_write
  • 03

    watch the staging deployment and tell me if it goes wrong.

    the subscription wakes the agent in this chat on the deployment event, and it reads the deployment and its pipeline before reporting back.

    bitbucket_subscribebitbucket_get_deploymentbitbucket_get_pipeline

what it will not do

repository administration, user management, and workspace settings are not in the tool set. an agent cannot reach a workspace the connection was never granted, and merging a pull request stays behind its own scope with its own approval prompt.

what agents can call

every Bitbucket tool an agent in a connected room can reach, split by whether it only reads or changes something. read tools are allowed by default, write tools stop for your approval, and the room's tool permissions can move any of them either way.

readallowed by default
  • bitbucket_get_commit

    Read a single commit.

  • bitbucket_get_file_contents

    Read a file from a repository.

  • bitbucket_git_sync

    Clone or fetch a repository to the room server.

  • bitbucket_list_commits

    List commits on a branch.

  • bitbucket_list_branches

    List repository branches.

  • bitbucket_list_repositories

    List workspace repositories.

  • bitbucket_get_repository

    Read repository metadata.

  • bitbucket_get_granted_scopes

    Read the connection's granted scopes.

  • bitbucket_list_pull_requests

    List pull requests in a repository.

  • bitbucket_pull_request_read

    Read a pull request, its diff, and comments.

  • bitbucket_list_pipelines

    List pipeline runs.

  • bitbucket_get_pipeline

    Read a pipeline run.

  • bitbucket_get_pipeline_steps

    Read a pipeline's steps.

  • bitbucket_get_pipeline_step_log

    Read a pipeline step's log.

  • bitbucket_list_deployments

    List deployments.

  • bitbucket_get_deployment

    Read a deployment.

  • bitbucket_list_deployment_environments

    List deployment environments.

writeasks by default
  • bitbucket_create_branch

    Create a new branch.

  • bitbucket_git_push

    Push commits to a repository.

  • bitbucket_create_pull_request

    Open a new pull request.

  • bitbucket_update_pull_request

    Update a pull request.

  • bitbucket_pull_request_review_write

    Approve or request changes on a pull request.

  • bitbucket_create_pull_request_comment

    Add a comment to a pull request.

  • bitbucket_merge_pull_request

    Merge a pull request.

  • bitbucket_configure_pipelines

    Enable or configure pipelines.

  • bitbucket_run_pipeline

    Trigger a pipeline run.

  • bitbucket_stop_pipeline

    Stop a running pipeline.

  • bitbucket_manage_deployment_environment

    Create, update, or delete a deployment environment.

  • bitbucket_manage_pipeline_variable

    Create, update, or delete a pipeline variable.

  • bitbucket_subscribe

    Subscribe the agent to events on a Bitbucket pull request, pipeline, or deployment.

  • bitbucket_unsubscribe

    Cancel one of the agent's Bitbucket event subscriptions.

what you grant

scopes are chosen when the room connects Bitbucket, and they can be changed later by reconnecting. anything marked off by default stays off until someone deliberately turns it on.

  • Read code & repos
    on by default

    Read commits, branches, file contents, and repository metadata; sync (clone/fetch) repositories to the room server.

  • Create branches & push
    on by defaultneeds repo_read

    Create new branches and push commits to workspace repositories.

  • Read pull requests
    on by default

    List and read pull requests, their diffs, and comments.

  • Write PRs & reviews
    on by defaultneeds pr_read

    Create and update pull requests, and write reviews and comments.

  • Merge pull requests
    on by defaultneeds pr_read

    Merge pull requests in workspace repositories.

  • Read pipelines & deployments
    on by default

    Read pipelines, steps, logs, deployments, and deployment environments.

  • Run & manage pipelines
    on by defaultneeds pipelines_read

    Enable and run pipelines, and manage environments and pipeline variables.

  • Event subscriptions
    on by default

    Let agents subscribe to Bitbucket events (pull requests, pipelines, deployments) and receive a notification in the chat where they subscribed.

how to connect Bitbucket

connecting Bitbucket takes one oauth round trip, started from inside the room that needs it.

  1. open the room's connectors settings

    connections belong to a room, not to your account and not to the team. open the room that needs Bitbucket and go to its connectors panel. connecting it in one room leaves every other room untouched.

  2. authorise with a real account

    any member of the room can start the oauth flow, and they authorise as themselves, so Bitbucket records a real identity on every action instead of an anonymous shared bot.

  3. choose the scopes for this room

    Bitbucket grants a fixed set at install, and the room decides which of those groups its agents may actually use. turn a group off and the tools behind it stop existing for that room, no reconnect needed.

  4. the room's agents pick up the tools

    every agent in that room can now call the Bitbucket tools the granted scopes cover. mutating tools still stop for approval, and disconnecting takes the tools away again in one click.

data handling and security

the objection to an agent with write access is noise: a wrong edit, a wrong comment, a wrong merge. the answer is that nothing mutating happens without a person, and nothing crosses a room boundary.

  • one connection, one room

    the Bitbucket credential is stored against the room it was authorised in. no tool in another room can read it, and there is no team-wide connection to inherit by accident.

  • scopes bound at the tool layer

    a Bitbucket tool that needs a scope the room did not grant is not offered to the agent at all, so a model cannot talk itself into an action nobody authorised.

  • approval before anything changes

    mutating tools pause the run and wait for a human. you allow once, allow always for that room, or deny, and the agent carries on with the answer.

  • an audit trail you can read

    every call is a message in the room's chat with its arguments and its result, in the order it happened, so a surprising change is traceable rather than mysterious.

  • revocation is one click

    disconnect Bitbucket and the tools disappear from the room immediately, along with the stored credential and any event subscriptions the agents had opened.

the permissions tab in room settings with reads on allow, edits on ask, and write file and bash on deny

the full approval model, including what agents ask you mid-run, is on human in the loop, and room isolation is on isolated rooms.

faq

can an ai agent open and review bitbucket pull requests?

yes. bitbucket_create_pull_request opens one, bitbucket_update_pull_request edits it, and bitbucket_pull_request_review_write approves or requests changes. all three are mutating tools, so the agent stops and asks before the first call unless the room already allows it.

can agents run bitbucket pipelines?

yes, with the run and manage pipelines scope. bitbucket_run_pipeline triggers a run, bitbucket_stop_pipeline cancels one, and bitbucket_get_pipeline_step_log pulls the log of the step that failed so the agent can read the real error instead of guessing at it.

what does the agent see without any write scopes?

commits, branches, file contents, repository metadata, pull requests with their diffs and comments, pipeline runs with their steps and logs, and deployments with their environments. that is enough for triage and review, and none of it changes anything in the workspace.

does this work with bitbucket cloud only?

the connector authorises against bitbucket cloud workspaces. once connected, bitbucket_list_repositories shows the repositories the granted access covers, and bitbucket_git_sync clones any of them onto the room server for the agents to work in.

can an agent change a pipeline variable?

bitbucket_manage_pipeline_variable exists behind the run and manage pipelines scope, and it asks before running. pipeline variables often hold deployment secrets, so most rooms leave that scope off and grant read pipelines and deployments only.

ready when you are

spin up your first room.

one room per client, project, or product, staffed with a project manager, an analyst, engineers and a reviewer.

Get startedSign in