Bitbucket Cloud
Issue trackers · publisher buff · version 1.1.0
Questions and answers right in bitbucket.org pull requests — where the review happens.
A question from a pull request in the Buff interface: the answer mentions export.py — a file that exists only on that pull request’s branch. The setup form — each integration has its own fields: address, scope, bot name and credentials. The connection is live: its own set of tools and its own allowed address. The connection check does not just say “ok”: it reports the account it signed in with and how many repositories are in scope. What the integration will get is written on its card in the connector’s catalogue.
Click a screenshot to open it in full. All screenshots are from a working installation.
Overview
The integration connects Buff to your workspace on bitbucket.org. A developer writes to the bot in a pull request discussion — the answer arrives there and is analysed against the code of THAT branch. Bitbucket Cloud no longer has an issue tracker of its own: Atlassian removed it from the API, so requests live in pull requests — as with Bitbucket Data Center, which has a separate integration with its own API. Your team’s tasks are connected through a separate integration of the tracker where they actually live.
Use cases
The situations it is installed for.
A question about the code right in the review
A reviewer has opened someone else’s pull request and does not understand why a change was needed in three places at once. Asking the author means waiting until tomorrow; reading the branch alone takes half a day.
Result. They write to the bot in the discussion. The answer arrives there and is analysed against the code of THIS branch: what changes, why the three places are linked and what it affects.
What really changes here
An eight-hundred-line pull request, and a simple question: what changes in substance, and what is missing.
Result. The bot reads the changes as a single diff and answers to the point — what changes, what is left unfinished, where the tests do not cover the new code path.
Tasks live in another tracker
Bitbucket Cloud no longer has a tracker of its own — Atlassian removed it — and the team’s tasks live in Jira, GitLab or Redmine.
Result. The review stays in Bitbucket, the tasks stay where they are: that tracker’s integration is installed alongside, and the bot answers in both places. There can be as many connections as you need.
The answer where it is expected
The person who asked for the change does not open the Buff interface and has no plans to. They need an answer in the discussion they opened.
Result. The finished analysis or a link to the development task arrives there as a comment. It is the only tool of the integration that writes anything — and it is unavailable at the stages where the model only reads.
Examples
What to write and what comes back. How the bot is addressed is set in the connection settings — here it is “@buff”.
@buff, what does this pull request change and what is it missing?
a comment in a pull request discussion
tool:
get_pull_diffThe branch adds building the CSV export: a new export.py module that takes the products in stock and calculates the discounted price. Missing: tests for an empty catalogue and for a product without a discount; the response header is sent without a charset — with Cyrillic that is the same old bug.
@buff, why was a separate cache needed here?
a comment in a pull request discussion
tool:
get_pullI read the pull request together with its discussion: the cache appeared after a complaint about export delays; two options were discussed and this one was chosen so as not to touch the shared layer. The description mentions this in a single line; the rest is in the comments.
/task finish the tests for an empty catalogue
a comment in a pull request discussion
tool:
get_pullThe word after the mention picks the work: without it — a short answer, “research” — deep research with a document, “task” — a draft development task with a link back to this discussion.
@buff, find pull requests about catalogue caching
a comment in any selected repository
tool:
search_pullsFound three: an open one, “TTL for the catalogue cache”, a merged one, “cache warm-up after a deploy”, and one closed without merging — there the cache was dropped in favour of a materialised view, and it is worth reading before trying again.
What it does
Answers against the branch of the pull request where it was asked
A question in a pull request discussion is a question about the code of THAT branch. The integration passes the branch along with the mention, Buff pulls it from your repository and computes the answer on it. An answer based on the main branch to a question about changes is not an answer but a coincidence.
Reads the whole pull request and issue
get_pull gives the model the description and the whole discussion — what the real intent of a change is made of. get_pull_diff brings the changes as a single diff. Both only read.
Searches the selected repositories
search_pulls goes only through the repositories you selected and finds related pull requests and issues. Also read only.
Answers where the question was asked
add_comment writes the answer to the same discussion. It is the only tool of the integration that changes anything — and it is unavailable at the stages where the model only reads. The connector checks that on its side.
Knows how it is addressed in Bitbucket
In Bitbucket Cloud a person has no login in the usual sense: there is a display name, a nickname and an account identifier, and the editor inserts a mention as `@{id}`. The integration recognises itself in all three forms — and so does not take its own answer for a new question.
Starts work only when addressed
An approval, an issue status change or a reviewer assignment starts nothing. The list of selected repositories is the access control: inside them any member can call the bot, outside them nobody can.
How to use it
Everything happens on the machine where the connector runs. At no step do you need to open access to your network from outside.
Step 1
Installation takes one click
Open the “Marketplace” section on the connector’s local page. Before installing you can see what the integration will get: the addresses it will be able to reach, which credentials it will ask for and how many tools the model will see. The connector downloads a signed bundle from our registry and checks the signature before writing anything to disk.
Connector← scroll the frame →
The access limits are written on the catalogue card. Step 2
Setup: an account, a token and a list of repositories
The API address is already filled in (`https://api.bitbucket.org`) — it exists as a field precisely so that you can see where the integration goes. Next you need the bot’s account and its app password (or an API token), plus the repositories as `workspace/repository`. The secret is stored on your machine; the integration does not see it.
Connector← scroll the frame →
Each integration has its own form fields. Step 3
Create a separate account for the bot
Invite it to the workspace and give it access only to the repositories needed: the account’s permissions are the outer boundary, and the list of selected repositories is the inner one. The app password needs only permission to read repositories and write to pull requests.
Step 4
The same from the command line
Installing without a GUI is an equal option, not a fallback: `connector install bitbucket-cloud`, then `connector instance add bitbucket-cloud --config base_url=https://api.bitbucket.org --config repos=acme/api`.
Step 5
Events arrive on their own
After setup there is nothing to start: the integration watches the selected repositories itself. If you want it faster, turn on event receiving in the connector and add a Bitbucket webhook for comments on pull requests and issues. Bitbucket Cloud does not sign its calls, so the pass is the secret in the link itself — the connector issues it itself and shows it to nobody else.
Connector← scroll the frame →
Each connection has its own set of tools and its own allowed address.
Access limits
The connector shows the same on your machine before installation. The list comes from the signed catalogue, not written here by hand.
Goes out to
only the addresses from the fields base_url
Credentials
api — the values stay in the connector, the integration does not see them
Webhooks
deliver — you open the port, if you choose to
| Tool | What it does | Access |
|---|---|---|
| search_pulls | Find pull requests by text — when a number is mentioned or context from a review is needed | read only |
| get_pull | Read a pull request with its discussion — when the intent of a change or the course of a review is needed | read only |
| get_pull_diff | Read a pull request’s changes as a single diff | read only |
| add_comment | Write a comment in a pull request | writes |
The integration runs as a separate process under its own operating system user: it does not see the connector’s key, does not read the files of other connections and cannot reach the network past the connector. More in the security section.
Requirements
- Bitbucket Cloud (bitbucket.org). Data Center and Server have a separate integration: their API is different.
- A bot account in your workspace and its app password or API token with permission to read repositories and write comments.
- Network access from the connector’s machine to bitbucket.org — nothing needs to be opened from your network to the outside.
- A connector run with the right to create a separate OS user for the integration (root or CAP_SETUID).
- For answers to be based on the code, connect the same repositories to Buff as a code source — by the same connector, in the “Repositories” section.
Questions
- We have Bitbucket Server, not the cloud. Will this work?
- No, Data Center and Server have a separate integration — their API is different. In the catalogue it is called Bitbucket Data Center.
- Does the app password go to your cloud?
- No. It is stored on the connector’s machine and never leaves it. The integration does not see it either: the connector inserts it into the outgoing request itself.
- Some of our repositories have the issue tracker turned off. Will that break the integration?
- No. The Bitbucket Cloud issue tracker has been removed from the API, so the integration always works in pull requests; the connection check confirms access to the selected repositories.
- Bitbucket does not sign webhooks. How do you tell a foreign call apart?
- The pass is the secret inside the link itself — the connector issues it, it cannot be guessed and is shown to nobody but you. A call with a wrong link never reaches the integration at all.
- Will the bot change statuses and close issues?
- No. The integration reads and writes comments. Statuses, reviewers and merging stay with your team.
Next
Connect Bitbucket Cloud
Install the connector in your network, open its local page and install the integration from the catalogue. Nothing needs to be rebuilt.
Companies and sole traders can pay by bank transfer and receive closing documents