GitLab

The integration connects Buff to your GitLab — installed in your network or in the cloud. A developer writes to the bot where the work is already happening: in an issue or under a merge request. Buff reads the discussion, answers with a comment in the same thread and, if asked, creates a development task with a link back. A question asked in a merge request is analysed against the code of ITS branch, not the main one.

• A question about the code right under the merge request

  A reviewer has opened someone else’s merge request and does not understand why a change was needed in three places at once. Asking the author means waiting until tomorrow; reading the whole branch alone takes half a day.

  Result. They write to the bot in a comment under the merge request. 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 development task from a discussion

  The issue has twenty comments, half the requirements appeared along the way, and nobody wants to rewrite the brief from scratch.

  Result. Buff reads the whole issue together with its discussion and drafts a development task from it. The link comes back as a comment, so GitLab stays the one place the team looks at.

• Reviewing changes without switching context

  An eight-hundred-line merge request, and a simple question: what does it really change, and what is missing.

  Result. The bot reads the changes as a list of diffs and answers to the point — what changes, what is left unfinished, where the tests do not cover the new code path. The answer sits in the merge request itself, next to the changes.

• This happened before — find where exactly

  An issue has come in that looks suspiciously like last year’s. Searching every project by hand takes a long time, and the only person who remembers it has left the company.

  Result. The integration searches the selected projects and brings back related issues and merge requests: duplicates, past requests about the same subsystem, the changes the current one depends on — with links.

1. @buff list what this merge request changes and what it is missing

   a comment under a merge request

   tool: get_merge_diff

   It changes three places: CSV parsing (a BOM is added), the response header (charset=utf-8 appears) and the export test. What is missing: the export from the scheduler takes another path and no BOM is added there — the file from the nightly job will open just as badly.

2. /research where the delay in the report comes from

   a comment in an issue — this is how deep research starts

   tool: get_issue

   Slash commands are familiar in GitLab, and they work: /ask, /research, /task. Addressing the bot by name is understood too — “@buff, take a look”. Without a command the bot simply answers the question.

3. @buff what has already been discussed in this issue?

   a comment in an issue with a long thread

   tool: get_issue

   A short summary of the discussion: what was asked for originally, which requirements were added along the way and in which comment, what was agreed and what remains unresolved. Useful when an issue is six months old and has thirty comments.

4. @buff find issues about catalogue caching

   a comment in any issue of a selected project

   tool: search_issues

   Found 4 discussions about caching: • acme/api#218 “Catalogue cache is not reset after a price change” — closed • acme/api!341 “Cache warm-up after a deploy” — merged • acme/api#402 “Duplicates in results after invalidation” — open, similar to the current one • acme/web#77 “Redis eats memory during exports” — open, discussion about TTL

1. 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, whether it will receive calls 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 →

2. Step 2

   Setup: an address, a token and a list of projects

   You need the address of your GitLab (or https://gitlab.com), a personal access token of the bot’s account with the api scope, and the projects in group/project form. The form is built from the schema the integration declares about itself. The token stays in the connector: the integration does not see it, the connector inserts it into outgoing requests itself.

   Connector

   

   ← scroll the frame →

3. Step 3

   Create a separate account for the bot

   Give it access only to the projects where the bot should answer: the account’s permissions are the outer boundary, and the list of selected projects is the inner one. The Reporter role is usually enough to read and comment; the bot should not be an administrator.

4. Step 4

   The same from the command line

   Installing without a GUI is an equal option, not a fallback: `connector install gitlab`, then `connector instance add gitlab --config base_url=… --config projects=acme/api`. On a server without X you do the same and get the same result.

5. Step 5

   Events arrive on their own

   After setup there is nothing to start: the integration watches the selected projects itself. If you want it faster, turn on event receiving in the connector: the address is set once for the whole machine, and the connection keeps only a switch. The connector issues the link and the secret itself; in the GitLab webhook, tick “Comments” (and, if you need discussions in merge requests, “Confidential comments” at your discretion). GitLab sends the secret back in a header, and the connector checks it.

   Connector

   

   ← scroll the frame →

6. Step 6

   Several servers — several connections

   Your own installation and gitlab.com, or two GitLabs for different teams, are two connections of one integration. Each has its own credentials, its own list of projects, its own development project and its own process under a separate OS user. Renaming breaks nothing: a connection lives under an identifier, not under a name.

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.

• Your own GitLab installation or gitlab.com — they share one API, only the address differs.
• A personal access token of the bot’s account with the api scope and access to the projects needed (the bot should not be an administrator).
• Network access from the connector’s machine to GitLab — 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).
• Commit comments are handled only with event receiving turned on: in GitLab’s event feed such a comment arrives without naming the commit, and the integration will not guess it.
• For a question from a merge request to be analysed against its branch, the repository must be connected to Buff as a code source. Otherwise the bot answers against the main branch and says so in the discussion itself.

Does the GitLab 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 GitLab?

No. It goes out only through the connector and only to addresses derived from the setup fields — that is, to the address of your GitLab, and only to API paths. The connector rejects everything else.

Will the bot be able to write to projects we did not select?

No. The list of selected projects limits both reading and writing: a mention from an unselected project does not start work, and an attempt to answer there is rejected by the connector itself. The bot account’s permissions are a second, independent boundary.

Is a question in a merge request analysed against its branch or the main one?

Against the branch of that merge request. The mention brings the project and the branch, the platform pulls a fresh copy of the repository and analyses the question on it. If the repository is not connected to Buff as a code source, the bot answers against the main branch and says so plainly in the answer.

What about commit comments?

They work with event receiving turned on: the call from GitLab carries the commit itself, and the answer is computed exactly on it. Polling will not see such comments — in the event feed GitLab does not say which commit a comment belongs to, and the integration will not invent an address.

How do I address the bot?

With a mention — “@buff, take a look” — or a slash command: /ask, /research, /task. Without a command the bot simply answers the question. Both forms work in an issue and in a merge request.

Can the bot start work on its own, without being addressed?

No. Labels and field changes do not count as addressing the bot: they are set by rules and bulk edits, and that would lead to work nobody ordered but that is billed. Assigning an issue to the bot is a way of addressing it, but it can be automatic too, so it is off by default.

Can the model accidentally write to an issue during analysis?

No. At the reading stages only the tools marked as reading are available. add_comment does not get there, and the connector checks that on its side, not we on ours.

Do I need to open a port for webhooks?

Not necessarily — except for commit comments. Polling always works and needs no ports; receiving calls speeds up the answer and adds that one scenario. The port is opened by the connector, one for all connections; the integrations themselves open no ports at all.