start here

start using Bitbucket with your agents

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

Start 7-day trial with Bitbucket
integrationsconnectorupdated
schematic diagram of the work aldena agents do through Bitbucket
Bitbucket

bitbucket ai agent: start runs from pull requests, pipelines and deployments

connect bitbucket to a project and its agents wake on pull request, pipeline and deployment events, sync repos to their conversation's sandbox, and push the branches they build.

events
13
resource types
3
access grants
4

bitbucket holds the pull requests, the pipelines and the deployments, and each of them is a moment when an agent could start work. connecting bitbucket to a project turns those moments into runs: an agent subscribes from a chat, and the next matching event starts a run in that chat, or in a new chat in the same project when the routine opens one per event. the same connection moves code between a workspace repository and the conversation's sandbox. pull requests, reviews and comments go through atlassian's rovo mcp server instead.

subscribing from a chat

bitbucket_subscribe takes a resource, the events to watch, and what the agent should do when one arrives. resources are always workspace/repo. a pull request routine covers every pull request in the repository, or one as workspace/repo#12. pipeline routines fire when a pipeline succeeds or fails, and deployment routines fire when a deployment succeeds, fails or stops, optionally for one environment such as production. bitbucket_unsubscribe takes an event routine off again, and the project's Settings → Routines lists every routine the agents hold.

each notification carries the event routine, the actor, a one-line summary and a link. a new pull request also carries its description, and a pull request comment carries the comment's text. that text is fenced off as untrusted data and capped at 4,000 characters.

moving code with git sync and push

bitbucket_git_sync clones a workspace repository into the conversation's sandbox, or fetches if it is already there. agents edit files and run the build and the tests over bash on real hardware, then bitbucket_git_push pushes the current branch or any refspec back, so a new branch needs no separate step. the git credential stays on the server side and never enters the agent's shell.

that is where the connector stops. it pushes a branch, but pull requests, reviews and comments need the mcp server.

going beyond triggers with atlassian's rovo mcp server

bitbucket has no server in the marketplace. it goes through atlassian's rovo mcp server, added by hand, and it acts as the atlassian account whose api token you give it.

  1. an atlassian org admin allows api token authentication for the rovo mcp server in atlassian administration. the bitbucket workspace has to be linked to that atlassian org.
  2. create an atlassian api token, then encode your atlassian email and the token as email:api-token in base64, for example with printf 'you@example.com:your-api-token' | base64.
  3. open the project's Settings → Connectors, and under MCP servers press Add MCP server.
  4. name it, for example atlassian-rovo, and set the url to https://mcp.atlassian.com/v2/mcp.
  5. switch on Send an authentication header, leave Header name as Authorization, enter Basic followed by the encoded value as the Token, and save.

some rovo mcp calls use atlassian's rovo credits, which atlassian bills to your org. once it is connected, agents reach its tools through mcp_search and mcp_call, each tool gets its own row in the project's permissions, and every action runs as the person whose token it is, not as aldena. the mcp servers page covers the rest.

example tasks

  • 01

    the nightly pipeline failed. find out why and push a fix.

    a pipeline routine starts the run with the failure in hand. the agent syncs the repo to the conversation's sandbox, reproduces the failure over bash, commits the fix, and pushes a branch.

    bitbucket_subscribebitbucket_git_syncbashbitbucket_git_push
  • 02

    when a pull request opens on the api repo, review it against our checklist.

    each new pull request starts a run with its description in the notification. the agent syncs the branch, runs the checks over bash, and leaves its review through the rovo mcp server, or in this chat when the project has none.

    bitbucket_subscribebitbucket_git_syncbashmcp_call
  • 03

    watch production deployments and tell me if one fails.

    a deployment routine filtered to production starts a run on each failure, and the agent reports it in this chat with the link to the deployment.

    bitbucket_subscribe

what it will not do

the connector does not read pull requests, pipelines or files through the bitbucket api, and it does not open, review, merge or comment on anything. repository administration, user management and workspace settings are out of reach. an agent cannot reach a workspace the connection was never given, and no event starts a run while the connection waits for a reconnect.

what starts a run

every Bitbucket event an agent can subscribe to, grouped by resource. an agent subscribes from a chat with bitbucket_subscribe, and each matching event starts a run in that chat, or in a new chat in the same project when the routine opens one per event.

pull request8 events
  • pr.created
  • pr.updated
  • pr.approved
  • pr.unapproved
  • pr.merged
  • pr.declined
  • pr.commented
  • review.changes_requested
pipeline2 events
  • pipeline.succeeded
  • pipeline.failed
deployment3 events
  • deployment.succeeded
  • deployment.failed
  • deployment.stopped

what you grant

aldena's Bitbucket app is configured for this access, and Bitbucket shows it on its own consent screen. every project gets the same set, and there is nothing to pick.

  • Repositories (write)

    Clone and fetch workspace repositories into the project's sandbox, push the branches agents create there, and read skill and agent files for the one-time import.

  • Pull requests (read)

    Check that a pull request an agent subscribes to exists.

  • Pipelines (read)

    Check the pipelines and deployments an agent subscribes to.

  • Webhooks

    Install the workspace webhook that delivers pull request, pipeline and deployment events.

how to connect Bitbucket

connecting Bitbucket takes one authorisation round trip, started from inside the project that needs it.

  1. open the project's connectors settings

    connections belong to a project, not to your account or the team. open the project that needs Bitbucket, go to settings → connectors, and press connect. other projects stay untouched.

  2. authorise with a real account

    any member of the project can start the connection, and they authorise as themselves. Bitbucket asks only for the fixed access listed above, with no scopes to choose.

  3. an agent subscribes from a chat

    ask an agent in a project chat to watch something in Bitbucket. it calls bitbucket_subscribe with the resource, events and intent, and settings → routines lists each routine it holds.

  4. a matching event starts a run

    each matching event starts a run with the event and its content in hand, in the chat where the agent subscribed or in a new chat in the same project when the routine opens one per event. disconnecting Bitbucket stops every subscription to it.

data handling and security

a connector holds one credential and turns Bitbucket events into runs. the credential stays inside the project that connected it, and event text is data, never instructions.

  • one connection, one project

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

  • tokens encrypted at rest

    the Bitbucket token is encrypted before it is stored, and it never appears in a chat or in an agent's prompt. agents get the events, not the credential.

  • events only where a routine watches

    aldena verifies each delivery came from Bitbucket. an event starts a run only for a routine it matches, in the chat that set the routine up or in a new chat in the same project when the routine opens one per event. nothing starts while the connection needs a reconnect.

  • event content is untrusted

    event text may come from a stranger. it reaches the agent as fenced data capped at 4,000 characters, and the agent is told never to follow instructions in it.

  • revocation is one click

    disconnect Bitbucket and the project's event routines on it stop at once, along with the stored credential.

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

each Bitbucket tool agents hold has its own allow, ask or deny row in the project's permissions. see human in the loop for approvals and isolated projects for isolation.

faq

what does the bitbucket connector let an agent do?

two things. it starts runs: an agent subscribes to pull request, pipeline or deployment events with bitbucket_subscribe, and each matching event starts a run in that chat, or in a new chat in the same project when the routine opens one per event. and it moves code: bitbucket_git_sync clones a workspace repository into the conversation's sandbox and bitbucket_git_push pushes the branches agents build there.

can an ai agent open and review bitbucket pull requests?

yes, through atlassian's rovo mcp server rather than the connector. add it by hand in the project's mcp servers with a basic authorization header built from your atlassian email and api token, and agents open, comment on and review pull requests through mcp_call, acting as you. the connector itself only pushes branches.

what does a bitbucket event notification contain?

the event routine, the actor, a one-line summary and a link. a new pull request also carries its description, and a pull request comment carries the comment's text. that text is fenced off as untrusted data and capped at 4,000 characters, and every other event arrives with the summary alone.

can an agent watch one deployment environment?

yes. a deployment routine covers a whole repository and takes an optional environment name, so an agent can wake only when production deploys succeed, fail or stop. pipeline routines are repository-wide and fire on every pipeline that succeeds or fails.

does this work with bitbucket cloud only?

yes. the connector authorises against a bitbucket cloud workspace, and you pick the workspace while connecting. aldena installs the workspace webhook that delivers events on every connect, and an agent can only subscribe to repositories in that workspace.

ready when you are

spin up your first project.

one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.