Gitea

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

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

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

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

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

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

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

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

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

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

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

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

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

1. @buff перечисли, что меняет этот pull request, и чего в нём не хватает

   комментарий под pull request

   инструмент: get_pull_diff

   Меняет три места: разбор CSV (добавлен BOM), заголовок ответа (появился charset=utf-8) и тест выгрузки. Не хватает: выгрузка из планировщика идёт другим путём и BOM там не добавляется — файл из ночной задачи откроется так же криво.

2. @buff research разберись, откуда берётся задержка в отчёте

   комментарий в задаче — так запускается глубокое исследование

   инструмент: get_issue

   Слово после обращения выбирает работу: без него — короткий ответ, «research» — глубокое исследование с документом, «task» — черновик задачи разработки. Привычная команда через слэш тоже работает: /research и /task.

3. /ask что уже обсуждали в этой задаче?

   комментарий в задаче с длинной перепиской

   инструмент: get_issue

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

4. @buff найди задачи про кеширование каталога

   комментарий в любой задаче отмеченного репозитория

   инструмент: search_issues

   Нашёл 4 обсуждения по кешированию: • acme/api#218 «Кеш каталога не сбрасывается после смены цены» — закрыт • acme/api#341 «Пустые ответы первые 30 секунд после деплоя» — закрыт, прогрев кеша • acme/api#402 «Дубли в выдаче после инвалидации» — открыт, похоже на текущее • acme/web#77 «Redis выедает память на выгрузках» — открыт, обсуждение про TTL

1. Шаг 1

   Установка занимает одно нажатие

   Откройте раздел «Маркетплейс» на локальной странице коннектора. До установки видно, что интеграция получит: адреса, по которым она сможет ходить, какие учётные данные попросит, будет ли принимать вызовы и сколько инструментов увидит модель. Коннектор скачивает подписанный бандл из нашего реестра и проверяет подпись до того, как что-то запишет на диск.

   Коннектор

   

2. Шаг 2

   Настройка — адрес, токен и список репозиториев

   Нужен адрес вашей Gitea, токен учётной записи бота и репозитории в формате владелец/репозиторий. Форма построена по схеме, которую интеграция объявляет о себе. Токен остаётся в коннекторе: интеграция его не видит, коннектор сам подставляет его в исходящие запросы.

   Коннектор

   

3. Шаг 3

   Заведите боту отдельную учётную запись

   Дайте ей доступ только к тем репозиториям, где бот должен отвечать: права учётной записи — это внешняя граница, а список отмеченных репозиториев — внутренняя. Токен достаточно выдать с правами на репозитории и задачи; администратором бот быть не должен.

4. Шаг 4

   То же самое из командной строки

   Установка без графики равноправна, а не запасной вариант: `connector install gitea`, затем `connector instance add gitea --config base_url=… --config repos=acme/api`. На сервере без иксов вы делаете то же самое и получаете тот же результат.

5. Шаг 5

   События приходят сами

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

   Коннектор

   

6. Шаг 6

   Несколько серверов — несколько подключений

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

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

• Gitea 1.20 или новее, либо совместимая Forgejo. Подходит и self-hosted, и сервер в вашем контуре.
• Токен учётной записи бота с правами на репозитории и задачи (администратором бот быть не должен).
• Сетевой доступ от машины с коннектором до Gitea — наружу из вашей сети ничего открывать не нужно.
• Коннектор, запущенный с правом заводить отдельного пользователя ОС для интеграции (root или CAP_SETUID).
• Чтобы вопрос из pull request разбирался по его ветке, репозиторий должен быть подключён к Buff как источник кода. Иначе бот ответит по основной ветке и скажет об этом в самом обсуждении.

Токен Gitea уходит к вам в облако?

Нет. Он хранится на машине с коннектором и не покидает её. Интеграция тоже его не видит: коннектор подставляет токен в исходящий запрос сам.

Может ли интеграция ходить куда-то, кроме нашей Gitea?

Нет. Наружу она ходит только через коннектор и только по адресам, выведенным из полей настройки, — то есть по адресу вашей Gitea, и только по путям API. Всё остальное коннектор отклоняет.

Бот сможет писать в репозитории, которые мы не отмечали?

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

Вопрос в pull request разбирается по его ветке или по основной?

По ветке этого pull request. Обращение приносит репозиторий и ветку, платформа подтягивает свежую копию репозитория и разбирает вопрос на ней. Если репозиторий не подключён к Buff как источник кода, бот ответит по основной ветке и честно скажет об этом в ответе — вместо того чтобы выдать разбор чужого кода за ответ на ваш вопрос.

Как обратиться к боту?

Упоминанием — «@buff, посмотри» — или командой через слэш: /ask, /research, /task. Без команды бот просто отвечает на вопрос. Обе формы работают и в задаче, и в pull request.

Может ли бот начать работу сам, без обращения?

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

Может ли модель случайно написать в задачу на этапе анализа?

Нет. Инструменты доступны только на читающих стадиях и только те, что помечены как читающие. add_comment туда не попадает, и проверяет это коннектор у себя, а не мы у себя.

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

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

Forgejo подойдёт?

Да. Forgejo — форк Gitea с тем же API, и интеграция работает с ней так же. Если версия окажется несовместимой, проверка связи скажет об этом прямо при настройке.