# GitLab — интеграция для Buff

> Вопросы и ответы прямо в задачах и merge request вашего GitLab — своей установки или gitlab.com, без разницы.

[Маркетплейс](https://buff.systems/marketplace) GitLab

# GitLab

Трекеры задач · издатель buff · версия 1.0.4

Вопросы и ответы прямо в задачах и merge request вашего GitLab — своей установки или gitlab.com, без разницы.

[Скачать коннектор](https://buff.systems/downloads) [Как установить](https://buff.systems/#usage) 3 из 4 инструментов только читают

- Ответ приходит комментарием в тот же merge request и разобран по его ветке.
- В задаче — то же самое: спросили в комментарии, ответ пришёл туда же.
- Форма настройки строится по схеме, которую интеграция объявляет о себе.
- Подключение работает: свой процесс, свой набор инструментов, свой разрешённый адрес.
- Проверка связи говорит не «ок», а версию GitLab, учётную запись и число проектов в области.
- Что интеграция получит, видно в каталоге коннектора до установки.

Нажмите на снимок, чтобы открыть его целиком. Все снимки — с работающей установки.

## Обзор

Интеграция связывает Buff с вашим GitLab — установленным в вашей сети или облачным. Разработчик пишет боту там, где и так идёт работа: в задаче или под merge request. Buff читает обсуждение, отвечает комментарием в тот же тред и, если попросили, заводит задачу разработки со ссылкой обратно. Вопрос, заданный в merge request, разбирается по коду ИМЕННО его ветки, а не по основной.

## Сценарии

Ситуации, ради которых его ставят.

- ### Вопрос по коду прямо под merge request Ревьюер открыл чужой merge request и не понимает, зачем понадобилась правка в трёх местах сразу. Спрашивать автора — ждать до завтра, читать всю ветку самому — полдня. Результат. Он пишет боту в комментарии под merge request. Ответ приходит туда же и разобран по коду ЭТОЙ ветки: что меняется, почему связаны три места и на что это влияет. Ревью продолжается в том же окне.
- ### Задача разработки из обсуждения В задаче двадцать комментариев, половина требований появилась по ходу обсуждения, и переписывать постановку заново никому не хочется. Результат. Buff читает задачу целиком, вместе с обсуждением, и заводит по ней черновик задачи разработки. Ссылка возвращается комментарием, так что GitLab остаётся единственным местом, куда смотрит команда.
- ### Разбор изменений без переключения контекста Merge request на восемьсот строк, а вопрос простой: что здесь меняется по существу и чего не хватает. Результат. Бот читает изменения списком diff и отвечает по делу — что меняется, что осталось недоделанным, где тесты не покрывают новую ветку кода. Ответ лежит в самом merge request, рядом с изменениями.
- ### Это уже было — найти, где именно Пришла задача, подозрительно похожая на прошлогоднюю. Искать вручную по всем проектам долго, а помнит её только тот, кто уволился. Результат. Интеграция ищет по отмеченным проектам и приносит связанные задачи и merge request: дубликаты, прошлые обращения по той же подсистеме, изменения, на которые опирается текущее — со ссылками.

## Примеры

Что написать и что придёт в ответ. Обращение к боту задаётся в настройках подключения — здесь это «@buff».

1. @buff перечисли, что меняет этот merge request, и чего в нём не хватает комментарий под merge request инструмент: `get_merge_diff` Меняет три места: разбор CSV (добавлен BOM), заголовок ответа (появился charset=utf-8) и тест выгрузки. Не хватает: выгрузка из планировщика идёт другим путём и BOM там не добавляется — файл из ночной задачи откроется так же криво.
2. /research разберись, откуда берётся задержка в отчёте комментарий в задаче — так запускается глубокое исследование инструмент: `get_issue` В GitLab привычна команда через слэш, и она работает: /ask, /research, /task. Обращение по имени тоже понимается — «@buff, посмотри». Без команды бот просто отвечает на вопрос.
3. @buff что уже обсуждали в этой задаче? комментарий в задаче с длинной перепиской инструмент: `get_issue` Краткая выжимка обсуждения: что просили изначально, какие требования добавились по ходу и в каком комментарии, о чём договорились и что осталось нерешённым. Полезно, когда задаче полгода и в ней тридцать комментариев.
4. @buff найди задачи про кеширование каталога комментарий в любой задаче отмеченного проекта инструмент: `search_issues` Нашёл 4 обсуждения по кешированию: • acme/api#218 «Кеш каталога не сбрасывается после смены цены» — закрыта • acme/api!341 «Прогрев кеша после деплоя» — влита • acme/api#402 «Дубли в выдаче после инвалидации» — открыта, похоже на текущее • acme/web#77 «Redis выедает память на выгрузках» — открыта, обсуждение про TTL

## Что умеет

### Отвечает по ветке того merge request, в котором спросили

Вопрос, заданный под merge request, — это вопрос о коде ЭТОГО merge request. Интеграция передаёт вместе с обращением проект и ветку, платформа подтягивает свежую копию репозитория и разбирает вопрос на его ветке, а не на основной. Ответ по основной ветке выглядел бы уверенно и был бы про другой код.

### Читает задачу или merge request целиком

get\_issue отдаёт модели описание и всё обсуждение — то, из чего складывается настоящая постановка: в заголовке «не работает поиск», а в третьем комментарии — что именно и на каких данных. get\_merge\_diff показывает изменения списком diff. Оба инструмента только читают.

### Ищет по отмеченным проектам

search\_issues ходит по проектам, которые вы отметили, и находит связанные задачи и merge request — дубликаты, прошлые обращения по той же подсистеме, изменения, на которые опирается текущее. Тоже только чтение.

### Отвечает в том же треде

add\_comment пишет ответ туда, где спросили: в задачу или в merge request. Это единственный инструмент интеграции, который что-то меняет, — и он недоступен на стадиях, где модель только читает. Проверяет это коннектор у себя.

### Слышит и обращение, и слэш-команду

Работает и упоминание — «@buff, посмотри», — и команда через слэш, привычная в GitLab: /ask, /research, /task. Без команды бот отвечает на вопрос. Опрос идёт по расписанию и не требует открытых портов; если GitLab есть куда стучаться, вызов доходит сразу — коннектор принимает его, проверяет секрет и отдаёт интеграции уже проверенное тело.

### Берётся за работу только по обращению

Метка или смена поля не запускают ничего: их ставят правила, массовые правки и автоматика самого GitLab, и работа, которую никто не заказывал, всё равно была бы оплачена. Назначение задачи на учётную запись бота — это обращение, но и оно бывает автоматическим, поэтому включается отдельной настройкой. Список отмеченных проектов и есть контроль доступа: внутри них позвать бота может любой участник, за их пределами — никто, и писать туда интеграция тоже не станет.

## Как пользоваться

Всё происходит на машине, где стоит коннектор. Открывать доступ к вашей сети снаружи не нужно ни на одном шаге.

1. Шаг 1 ### Установка занимает одно нажатие Откройте раздел «Маркетплейс» на локальной странице коннектора. До установки видно, что интеграция получит: адреса, по которым она сможет ходить, какие учётные данные попросит, будет ли принимать вызовы и сколько инструментов увидит модель. Коннектор скачивает подписанный бандл из нашего реестра и проверяет подпись до того, как что-то запишет на диск. **Коннектор** Границы доступа видны в каталоге до установки.
2. Шаг 2 ### Настройка — адрес, токен и список проектов Нужен адрес вашего GitLab (или https://gitlab.com), personal access token учётной записи бота со скоупом api и проекты в формате группа/проект. Форма построена по схеме, которую интеграция объявляет о себе. Токен остаётся в коннекторе: интеграция его не видит, коннектор сам подставляет его в исходящие запросы. **Коннектор** Форма настройки строится по схеме интеграции.
3. Шаг 3 ### Заведите боту отдельную учётную запись Дайте ей доступ только к тем проектам, где бот должен отвечать: права учётной записи — это внешняя граница, а список отмеченных проектов — внутренняя. Роли Reporter обычно достаточно, чтобы читать и комментировать; администратором бот быть не должен.
4. Шаг 4 ### То же самое из командной строки Установка без графики равноправна, а не запасной вариант: \`connector install gitlab\`, затем \`connector instance add gitlab --config base\_url=… --config projects=acme/api\`. На сервере без иксов вы делаете то же самое и получаете тот же результат.
5. Шаг 5 ### События приходят сами После настройки ничего запускать не нужно: интеграция сама следит за отмеченными проектами. Хотите быстрее — включите приём событий у коннектора: адрес указывается один раз на всю машину, а у подключения остаётся только выключатель. Ссылку и секрет коннектор выдаёт сам; в вебхуке GitLab отметьте «Comments» (и, если нужны обсуждения в merge request, «Confidential comments» по вашему усмотрению). Секрет GitLab присылает обратно в заголовке, и коннектор его сверяет. **Коннектор** Каждое подключение — отдельный процесс со своим набором инструментов.
6. Шаг 6 ### Несколько серверов — несколько подключений Своя установка и gitlab.com, или два GitLab для разных команд — это два подключения одной интеграции. У каждого свои учётные данные, свой список проектов, свой проект разработки и свой процесс под отдельным пользователем ОС. Переименование ничего не ломает: подключение живёт под идентификатором, а не под названием.

## Границы доступа

То же самое коннектор показывает на вашей машине до установки. Список берётся из подписанного каталога, а не написан здесь руками.

Ходит наружу

только по адресам из полей `base_url`

Учётные данные

api — значения остаются в коннекторе, интеграция их не видит

Вебхуки

deliver — порт открываете вы, по желанию

| Инструмент | Что делает | Доступ |
| --- | --- | --- |
| search\_issues | Найти задачи и merge request по тексту — когда упомянут номер или нужен контекст из трекера | только чтение |
| get\_issue | Прочитать задачу или merge request с обсуждением — когда нужны требования или ход обсуждения | только чтение |
| get\_merge\_diff | Прочитать изменения merge request списком diff | только чтение |
| add\_comment | Написать комментарий в задачу или merge request | пишет |

Интеграция работает отдельным процессом под собственным пользователем операционной системы: она не видит ключа коннектора, не читает файлы других подключений и не может выйти в сеть мимо коннектора. Подробнее — в [разделе о безопасности](https://buff.systems/security).

## Требования

- GitLab своей установки или gitlab.com — API у них общий, отличается только адрес.
- Personal access token учётной записи бота со скоупом api и доступом к нужным проектам (администратором бот быть не должен).
- Сетевой доступ от машины с коннектором до GitLab — наружу из вашей сети ничего открывать не нужно.
- Коннектор, запущенный с правом заводить отдельного пользователя ОС для интеграции (root или CAP\_SETUID).
- Комментарии к коммитам обрабатываются только при включённом приёме событий: в ленте событий GitLab такой комментарий приходит без указания коммита, и угадывать его интеграция не станет.
- Чтобы вопрос из merge request разбирался по его ветке, репозиторий должен быть подключён к Buff как источник кода. Иначе бот ответит по основной ветке и скажет об этом в самом обсуждении.

## Вопросы

- **Токен GitLab уходит к вам в облако?**: Нет. Он хранится на машине с коннектором и не покидает её. Интеграция тоже его не видит: коннектор подставляет токен в исходящий запрос сам.
- **Может ли интеграция ходить куда-то, кроме нашего GitLab?**: Нет. Наружу она ходит только через коннектор и только по адресам, выведенным из полей настройки, — то есть по адресу вашего GitLab, и только по путям API. Всё остальное коннектор отклоняет.
- **Бот сможет писать в проекты, которые мы не отмечали?**: Нет. Список отмеченных проектов ограничивает и чтение, и запись: обращение из неотмеченного проекта не запускает работу, а попытка ответить туда отклоняется самим коннектором. Права учётной записи бота — вторая, независимая граница.
- **Вопрос в merge request разбирается по его ветке или по основной?**: По ветке этого merge request. Обращение приносит проект и ветку, платформа подтягивает свежую копию репозитория и разбирает вопрос на ней. Если репозиторий не подключён к Buff как источник кода, бот ответит по основной ветке и честно скажет об этом в ответе.
- **А комментарии к коммитам?**: Работают при включённом приёме событий: вызов от GitLab несёт сам коммит, и ответ считается ровно на нём. Опрос такие комментарии не увидит — в ленте событий GitLab не сообщает, к какому коммиту относится комментарий, и выдумывать адрес интеграция не будет.
- **Как обратиться к боту?**: Упоминанием — «@buff, посмотри» — или командой через слэш: /ask, /research, /task. Без команды бот просто отвечает на вопрос. Обе формы работают и в задаче, и в merge request.
- **Может ли бот начать работу сам, без обращения?**: Нет. Метки и смена полей не считаются обращением: их ставят правила и массовые правки, и это привело бы к работе, которую никто не заказывал, но за которую выставлен счёт. Назначение задачи боту — обращение, но оно тоже бывает автоматическим, поэтому по умолчанию выключено.
- **Может ли модель случайно написать в задачу на этапе анализа?**: Нет. Инструменты доступны только на читающих стадиях и только те, что помечены как читающие. add\_comment туда не попадает, и проверяет это коннектор у себя, а не мы у себя.
- **Нужно ли открывать порт для вебхуков?**: Не обязательно — кроме случая с комментариями к коммитам. Опрос работает всегда и портов не требует; приём вызовов ускоряет ответ и добавляет тот единственный сценарий. Порт открывает коннектор, один на все подключения; сами интеграции портов не открывают вовсе.

Коротко

- **Версия**: 1.0.4
- **Издатель**: buff
- **Обновлён**: 2026-09-06
- **Размер**: 20 КБ
- **Инструментов**: 4, только читают 3
- **Учётные данные**: api
- **Вебхуки**: deliver
- **Платформы**: linux-x86\_64, linux-aarch64

[Документация коннектора](https://buff.systems/docs/connector) [Как это устроено с точки зрения ИБ](https://buff.systems/security) [Задать вопрос об интеграции](https://buff.systems/contact)

На этой странице

- [Обзор](https://buff.systems/#overview)
- [Сценарии](https://buff.systems/#use-cases)
- [Примеры](https://buff.systems/#examples)
- [Что умеет](https://buff.systems/#abilities)
- [Как пользоваться](https://buff.systems/#usage)
- [Границы доступа](https://buff.systems/#access)
- [Требования](https://buff.systems/#requirements)
- [Вопросы](https://buff.systems/#faq)

Дальше

## Подключить GitLab

Поставьте коннектор в своей сети, откройте его локальную страницу и установите интеграцию из каталога. Пересобирать ничего не нужно.

[Скачать коннектор](https://buff.systems/app) [Написать нам](mailto:info@buff.systems)

Юрлицам и ИП — оплата переводом по реквизитам и закрывающие документы