GitLab

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

• Вопрос по коду прямо под merge request

  Ревьюер открыл чужой merge request и не понимает, зачем понадобилась правка в трёх местах сразу. Спрашивать автора — ждать до завтра, читать всю ветку самому — полдня.

  Результат. Он пишет боту в комментарии под merge request. Ответ приходит туда же и разобран по коду ЭТОЙ ветки: что меняется, почему связаны три места и на что это влияет. Ревью продолжается в том же окне.

• Задача разработки из обсуждения

  В задаче двадцать комментариев, половина требований появилась по ходу обсуждения, и переписывать постановку заново никому не хочется.

  Результат. Buff читает задачу целиком, вместе с обсуждением, и заводит по ней черновик задачи разработки. Ссылка возвращается комментарием, так что GitLab остаётся единственным местом, куда смотрит команда.

• Разбор изменений без переключения контекста

  Merge request на восемьсот строк, а вопрос простой: что здесь меняется по существу и чего не хватает.

  Результат. Бот читает изменения списком diff и отвечает по делу — что меняется, что осталось недоделанным, где тесты не покрывают новую ветку кода. Ответ лежит в самом merge request, рядом с изменениями.

• Это уже было — найти, где именно

  Пришла задача, подозрительно похожая на прошлогоднюю. Искать вручную по всем проектам долго, а помнит её только тот, кто уволился.

  Результат. Интеграция ищет по отмеченным проектам и приносит связанные задачи и merge request: дубликаты, прошлые обращения по той же подсистеме, изменения, на которые опирается текущее — со ссылками.

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

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 для разных команд — это два подключения одной интеграции. У каждого свои учётные данные, свой список проектов, свой проект разработки и свой процесс под отдельным пользователем ОС. Переименование ничего не ломает: подключение живёт под идентификатором, а не под названием.

Интеграция работает отдельным процессом под собственным пользователем операционной системы: она не видит ключа коннектора, не читает файлы других подключений и не может выйти в сеть мимо коннектора. Подробнее — в разделе о безопасности.

• 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 туда не попадает, и проверяет это коннектор у себя, а не мы у себя.

Нужно ли открывать порт для вебхуков?

Не обязательно — кроме случая с комментариями к коммитам. Опрос работает всегда и портов не требует; приём вызовов ускоряет ответ и добавляет тот единственный сценарий. Порт открывает коннектор, один на все подключения; сами интеграции портов не открывают вовсе.