GitHub
Issue trackers · publisher buff · version 1.1.0
Questions and answers right in GitHub issues and pull requests — both in the github.com cloud and in Enterprise Server inside your network.
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 where you are, the account you 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 GitHub. The team keeps working where it is used to: in the issue and in the pull request discussion. A question asked under a pull request is analysed against the code of ITS branch — not the main one — and the answer arrives there as a comment. The same integration works with github.com and with GitHub Enterprise Server: they share one API, only the address differs.
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. The review continues in the same window.
A question about the code without leaving the issue
A tester has filed an issue “CSV export breaks on Cyrillic” and does not know where to dig.
Result. They mention the bot in a comment. A few minutes later the issue holds an analysis: where the export is built, why the encoding is lost and what will have to change.
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. The answer sits next to the changes.
The answer where it is expected
The person who requested the task does not open the Buff interface and has no plans to. They need an answer in the issue they opened.
Result. The finished analysis or a link to the development task arrives as a comment in the original issue. 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, find out why Cyrillic breaks on export
a comment in an issue
tool:
get_issueI read the whole issue together with its discussion and traced it through the code. The file is served without a BOM and with a text/csv header without a charset — Excel on Windows reads such a file as cp1251. I attached the analysis with the places in the code as a document and posted a link to it here.
/research where the delay in the export comes from
a comment in an issue or pull request
tool:
get_issueThe word after the mention picks the work: without it — a short answer, “research” — deep research with a document, “task” — a draft development task. The familiar slash command works the same way as addressing the bot by name.
@buff, find issues about catalogue caching
a comment in any selected repository
tool:
search_issuesFound 4 items about caching: two closed issues about resetting the cache after a price change and warming it up after a deploy, an open pull request about TTL and an issue about duplicates in results — it is similar to the current one.
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 issue and pull request
get_issue gives the model the description and the whole discussion — what a real brief is made of: the title says “search does not work”, and the third comment says what exactly and on which data. get_pull_diff brings the changes as a single diff. Both only read.
Searches the selected repositories
search_issues goes only through the repositories you selected and finds related issues and pull requests — duplicates, past requests about the same subsystem, the changes the current one depends on. Also read only.
Answers where the question was asked
add_comment writes the answer to the same issue or pull request. 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.
Starts work only when addressed
A label, a status change or a review request starts nothing: those are set by rules and bulk edits, and work nobody ordered would still be billed. Assigning an issue to the bot’s account is a way of addressing it, but it can be automatic too, so it is turned on by a separate setting. The list of selected repositories is the access control: inside them any member can call the bot, outside them nobody can.
Never touches your process
The integration does not change statuses, move issues across the board, assign people or close issues. It reads and writes comments — nothing more. Your process stays yours.
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 address, a token and a list of repositories
For github.com the API address is already filled in (`https://api.github.com`); for Enterprise Server enter `https://your-server/api/v3`. Next come a token of the bot’s account and the repositories as `owner/repository`. The token is stored on your machine; the integration itself does not see it — the connector inserts it into the outgoing request itself.
Connector← scroll the frame →
Each integration has its own form fields. Step 3
Create a separate account for the bot
On github.com this is a machine account — which the rules explicitly allow. Give it access only to the repositories where the bot should answer: the account’s permissions are the outer boundary, and the list of selected repositories is the inner one. A classic token with the `repo` scope, or a fine-grained one with permissions on contents, issues and pull requests.
Step 4
The same from the command line
Installing without a GUI is an equal option, not a fallback: `connector install github`, then `connector instance add github --config base_url=https://api.github.com --config repos=acme/api`. On a server without X you do the same and get the same result.
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 GitHub webhook for the Issue comments and Pull request review comments events; the connector issues the link and the secret itself and checks GitHub’s signature (`X-Hub-Signature-256`).
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_issues | Find issues and pull requests by text — when a number is mentioned or context from the tracker is needed | read only |
| get_issue | Read an issue or pull request with its discussion — when requirements or the course of a discussion are needed | read only |
| get_pull_diff | Read a pull request’s changes as a single diff | read only |
| add_comment | Write a comment in an issue or 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
- GitHub — github.com or Enterprise Server; they share one API, only the address differs.
- A token of the bot’s account with permission to read repositories and write comments in issues and pull requests.
- Network access from the connector’s machine to GitHub — 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
- Does the GitHub token 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 the token into the outgoing request itself.
- Can the integration reach anything other than our GitHub?
- No. The address it is allowed to reach is derived from your own “API address” field, and the connector does not let a request go beyond it. What exactly is allowed is visible in the catalogue before installation.
- Will the bot change statuses and close issues?
- No. The integration reads and writes comments. Statuses, labels, assignees and closing issues stay with your team.
- Our Enterprise Server is inside our network and closed to the outside. Will it work?
- Yes, that is what the connector is for: it sits inside your perimeter, goes to your GitHub itself and reaches Buff itself. No incoming connections into your network are needed.
- Will the bot answer a comment it wrote itself?
- No. It knows its own account and does not take its own answers for new questions.
Next
Connect GitHub
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