# Gitea — an integration for Buff

> Questions and answers right in the issues and pull requests of your Gitea or Forgejo — where the team already discusses the code.

[Marketplace](https://buff.systems/en/marketplace) Gitea

# Gitea

Issue trackers · publisher buff · version 1.1.0

Questions and answers right in the issues and pull requests of your Gitea or Forgejo — where the team already discusses the code.

[Download the connector](https://buff.systems/en/downloads) [How to install](https://buff.systems/en/marketplace/gitea#usage) 3 of 4 tools only read

- The answer arrives as a comment in the same pull request and is analysed against its branch.
- In an issue it is the same: asked in a comment, the answer comes back there.
- 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 Gitea version, the account and the number of repositories 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 Gitea from inside your own network. A developer writes to the bot where the discussion is already happening: in an issue or under a pull request. Buff reads the discussion, answers with a comment in the same thread and — if asked — drafts a development task with a link back. A question asked in a pull request is analysed against the code of THAT branch, not the main one.

## Use cases

The situations it is installed for.

- ### A question about the code right under the pull request 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 whole branch alone takes half a day. Result. They write to the bot in a comment under the pull 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 the tracker stays the one place the team looks at.
- ### This happened before — find where exactly An issue has come in that looks suspiciously like last year’s. Searching every repository by hand takes a long time, and the only person who remembers it has left the company. Result. The integration searches the selected repositories and brings back related issues and pull requests: duplicates, past requests about the same subsystem, the changes the current one depends on — with links.
- ### Reviewing changes without switching context An eight-hundred-line pull request, and a simple question: what does it really change, 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 in the pull request itself, next to the changes.

## Examples

What to write and what comes back. How the bot is addressed is set in the connection settings — here it is “@buff”.

1. @buff list what this pull request changes and what it is missing a comment under a pull request tool: `get_pull_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. @buff research where the delay in the report comes from a comment in an issue — this is how deep research starts tool: `get_issue` The 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 too: /research and /task.
3. /ask 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 repository tool: `search_issues` Found 4 discussions about caching: • acme/api#218 “Catalogue cache is not reset after a price change” — closed • acme/api#341 “Empty responses for the first 30 seconds after a deploy” — closed, cache warm-up • 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

## What it does

### Answers against the branch of the pull request it was asked in

A question asked under a pull request is a question about the code of THAT pull request. The integration passes the repository and the branch along with the mention, the platform pulls a fresh copy of the repository and analyses the question on its branch, not on the main one. An answer based on the main branch would look confident and be about different code.

### Reads the whole issue or 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 shows the changes as a single diff. Both tools only read.

### Searches the selected repositories

search\_issues goes 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 in the same thread

add\_comment writes the answer where the question was asked: in the issue or in the 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.

### Hears both a mention and a familiar command

Both a mention — “@buff, take a look” — and the slash commands familiar in Gitea work: /ask, /research, /task. Without a command the bot answers the question. Polling runs on a schedule and needs no open ports; if Gitea has somewhere to call, the call arrives at once — the connector receives it, checks the secret and the signature and hands the integration a body that has already been verified.

### Starts work only when addressed

A label or a field change starts nothing: those are set by rules, bulk edits and the tracker’s own automation, 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, and the integration will not write there either.

## 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.

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 → The access limits are written on the catalogue card.
2. Step 2 ### Setup: an address, a token and a list of repositories You need the address of your Gitea, a token of the bot’s account and the repositories in owner/repository 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 → Each integration has its own form fields.
3. Step 3 ### Create a separate account for the bot 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 token with permissions on repositories and issues is enough; 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 gitea\`, then \`connector instance add gitea --config base\_url=… --config repos=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 repositories 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 for the Gitea webhook itself; it generates the secret inside it and does not show it. The connector checks the Gitea signature — in all three forms Gitea sends. **Connector** ← scroll the frame → Each connection has its own set of tools and its own allowed address.
6. Step 6 ### Several servers — several connections Two Giteas, or one Gitea for different teams, are two connections of one integration. Each has its own credentials, its own list of repositories, 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.

## 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](https://buff.systems/en/security).

## Requirements

- Gitea 1.20 or later, or a compatible Forgejo. Both self-hosted and a server inside your perimeter work.
- A token of the bot’s account with permissions on repositories and issues (the bot should not be an administrator).
- Network access from the connector’s machine to Gitea — 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 a question from a pull 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.

## Questions

- **Does the Gitea 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 Gitea?**: No. It goes out only through the connector and only to addresses derived from the setup fields — that is, to the address of your Gitea, and only to API paths. The connector rejects everything else.
- **Will the bot be able to write to repositories we did not select?**: No. The list of selected repositories limits both reading and writing: a mention from an unselected repository 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 pull request analysed against its branch or the main one?**: Against the branch of that pull request. The mention brings the repository 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 — rather than passing off an analysis of other code as the answer to your question.
- **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 pull 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. Polling always works and needs no ports; receiving calls is a speed-up for those who have somewhere to direct it. The port is opened by the connector, one for all connections; the integrations themselves open no ports at all.
- **Will Forgejo work?**: Yes. Forgejo is a fork of Gitea with the same API, and the integration works with it the same way. If the version turns out to be incompatible, the connection check says so right during setup.

At a glance

- **Version**: 1.1.0
- **Publisher**: buff
- **Updated**: 2026-10-05
- **Size**: 23 KB
- **Tools**: 4, 3 read only
- **Credentials**: api
- **Webhooks**: deliver
- **Platforms**: linux-x86\_64, linux-aarch64

[Connector documentation](https://buff.systems/en/docs/connector) [How it works from an information security standpoint](https://buff.systems/en/security) [Ask a question about the integration](https://buff.systems/en/contact)

On this page

- [Overview](https://buff.systems/en/marketplace/gitea#overview)
- [Use cases](https://buff.systems/en/marketplace/gitea#use-cases)
- [Examples](https://buff.systems/en/marketplace/gitea#examples)
- [What it does](https://buff.systems/en/marketplace/gitea#abilities)
- [How to use it](https://buff.systems/en/marketplace/gitea#usage)
- [Access limits](https://buff.systems/en/marketplace/gitea#access)
- [Requirements](https://buff.systems/en/marketplace/gitea#requirements)
- [Questions](https://buff.systems/en/marketplace/gitea#faq)

Next

## Connect Gitea

Install the connector in your network, open its local page and install the integration from the catalogue. Nothing needs to be rebuilt.

[Download the connector](https://buff.systems/app) [Write to us](mailto:info@buff.systems)

Companies and sole traders can pay by bank transfer and receive closing documents