Интеграции с трекерами
Как команда работает с ботом в своём трекере: обращения, команды, область видимости, ветка pull request, события.
Интеграция с трекером даёт одно: команда обращается к Buff там, где уже работает — в тикете, в задаче, в обсуждении pull request. Вопрос задают комментарием, ответ приходит туда же.
Все трекерные интеграции ведут себя одинаково; отличается только то, чего в конкретном трекере нет. Различия — в таблице ниже.
Как обратиться к боту
Работа запускается только прямым обращением. Это решение, а не ограничение: метки и статусы меняют правила автоматизации и массовые правки, и запуск по ним означал бы работу, которую никто не заказывал, но кто-то оплатил.
Обратиться можно двумя способами, оба работают везде:
| Форма | Пример | Когда удобнее |
|---|---|---|
| Упоминание | @buffbot почему падает экспорт? | привычно в трекере задач |
| Команда через слэш | /ask почему падает экспорт? | привычно в GitHub, GitLab, Gitea |
Полезные подробности:
- Регистр не важен.
@Buff,@BUFFBOT,/Research— всё это обращения. - Псевдоним. Кроме учётной записи бота работает короткое имя из настройки
подключения (
mention_alias), обычно@buff. - Автодополнение трекера тоже подходит: вставленное упоминание распознаётся, как и набранное руками.
- Текст вокруг обращения учитывается — можно сначала описать контекст, а потом попросить.
- Повторное обращение в том же тикете продолжает тот же разговор: можно уточнять, не начиная с нуля.
- Чужие обращения бот не перехватывает:
@buffalo— это другой человек.
Что можно попросить
| Что написать | Что произойдёт |
|---|---|
@buff почему падает экспорт? | вопрос — разбор по коду, ответ комментарием |
@buff research откуда растёт задержка или /research … | глубокое исследование — выверенный документ, ссылка и файл придут туда же |
@buff task починить экспорт CSV или /task … | черновик задачи разработки в Buff и ссылка на него |
@buff ask где лежит конфиг или /ask … | то же, что без команды — вопрос, только явно |
Без команды это вопрос: самый частый случай и потому умолчание.
task создаёт черновик, а не запускает разработку. Согласование формулировки —
осознанный шаг, и он остаётся в Buff.
Область видимости — это контроль доступа
У каждого подключения есть список: репозитории или ключи проектов, где бот работает. Список действует в обе стороны — в неотмеченных местах бот не читает обращения и не пишет ответы.
Пустой список означает «нигде», а не «везде». Подключение без явно указанных репозиториев или проектов не отвечает нигде — это защита от «поставил и забыл настроить область».
Права учётной записи бота в трекере — внешняя граница, список — внутренняя. Разумно иметь обе: доступ бота ограничен тем, что ему выдали, а внутри — тем, что вы отметили.
Ответ по коду того места, где спросили
Вопрос, заданный в обсуждении pull request, — это вопрос про код этой ветки. Интеграция передаёт ветку вместе с обращением, платформа подтягивает её из вашего репозитория и считает ответ на ней.
| Где спросили | На каком коде считается ответ |
|---|---|
| задача / тикет | код проекта разработки, к которому привязано подключение |
| pull request / merge request | ветка этого pull request |
| комментарий к коммиту | ветка, на которую указывает событие; иначе — основная |
Чтобы это работало, репозиторий должен быть подключён к Buff как источник кода — тем же коннектором, в разделе «Репозитории». Если он не подключён, бот всё равно ответит по основной ветке проекта и прямо скажет об этом в тикете: ответ, посчитанный по другому коду и выданный за ответ на этот pull request, хуже, чем никакого.
Что бот пишет в тикет
- Сразу — короткое «принял, работаю»: исследование идёт минутами, и без этого непонятно, услышал ли бот вообще.
- Ссылку — на обсуждение, черновик или исследование в Buff. Там, где трекер умеет хранить ссылки отдельно (Jira), она попадает в блок ссылок тикета, а не тонет в ленте комментариев.
- Результат — готовый ответ комментарием. Для исследования — ещё и сам документ: там, где трекер принимает вложения, PDF прикладывается к тикету.
Если данных не хватает, бот задаст уточняющий вопрос в том же тикете и дождётся ответа. Если что-то не получилось — тоже напишет: молчание читалось бы как поломка.
Статусы, метки, исполнителей и поля бот не трогает никогда. Ни одна трекерная интеграция не имеет для этого инструмента: единственный пишущий инструмент — комментарий, и модели он не отдаётся.
Назначение задачи боту
Назначение — пограничный случай: задача действительно адресована боту, но назначают и по правилам маршрутизации, когда работу никто не заказывал. Поэтому оно выключено по умолчанию и включается галочкой «Принимать задачи, назначенные боту» — если у вас назначает человек осознанно.
События: опрос и вебхуки
Опрос работает всегда. Каждое подключение читает свой трекер раз в 20 секунд, и для этого не нужно открывать наружу ни одного порта — соединение исходящее. Для закрытого периметра это рабочий режим по умолчанию.
Вебхуки только ускоряют доставку. Приёмник принадлежит коннектору — один адрес на все подключения, настраивается в разделе «Подключение». У самого подключения есть только выключатель: ссылку с секретом выдаёт коннектор, придумывать её не нужно.
Эта ссылка сама по себе пароль: в ней зашит секрет. Не публикуйте её. Там, где трекер умеет подписывать свои вызовы, коннектор проверяет ещё и подпись — своим алгоритмом для каждого трекера. Секрет переживает переименование подключения, так что ссылку не придётся менять.
Куда вставлять ссылку и на какие события подписываться:
| Трекер | Где | События |
|---|---|---|
| Gitea / Forgejo | Настройки репозитория → Веб-хуки → Gitea | Issue Comment и Pull Request Comment (одного мало) |
| GitLab | Настройки → Веб-хуки, поле Secret token | Comments (note events) |
| GitHub / GHES | Settings → Webhooks, content type application/json, Secret | Issue comments, Pull request review comments, Commit comments |
| Bitbucket Data Center | Настройки репозитория → Webhooks | Pull request → Comment added |
| Bitbucket Cloud | Repository settings → Webhooks | Pull request → Comment created; Issue → Comment created |
| Jira DC / Server / Cloud | Администрирование → Система → Вебхуки | Issue updated, Comment created (можно сузить JQL) |
| Redmine | — | вебхуков нет; работает опрос |
Старые обращения бот не разгребает. Отсчёт для нового подключения начинается с момента, когда вы его включили: тикеты, написанные до этого, не будут внезапно отвечены задним числом.
Какой трекер что умеет
| Интеграция | Задачи | Pull / merge request | Коммиты | Как адресуется тред | Вебхуки |
|---|---|---|---|---|---|
jira (DC, Server) | да | — | — | PROJ-7 | да, с подписью |
jira-cloud | да | — | — | PROJ-7 | да, секрет в ссылке |
gitea (+ Forgejo) | да | да | — | acme/api#7 | да, с подписью |
gitlab (self-hosted и gitlab.com) | да | да | да | group/app#7, !7, @sha | да, с проверкой токена |
github (+ Enterprise Server) | да | да | да | acme/api#7, acme/api@sha | да, с подписью |
bitbucket-dc | — | да | — | ACME/api!7 | да, с подписью |
bitbucket-cloud | да, где включён трекер репозитория | да | — | acme/api!7, #7 | да, секрет в ссылке |
redmine | да | — | — | catalog#7 | нет |
Кроме трекеров в каталоге есть источники знаний — Confluence: там бот не ведёт задачи, а читает написанное командой и отвечает в обсуждении страницы. Отдельная страница: «Источники знаний».
У Bitbucket Data Center своего трекера задач нет — интеграция живёт в pull request. Если задачи у вас в Jira или Redmine, поставьте рядом их интеграцию: подключений может быть сколько угодно, и у каждого свой проект разработки.
Что уходит к нам из трекера
Только то, без чего запрос не выполнить, и только по прямому обращению:
- текст обращения (без остального содержимого тикета — его модель читает инструментом, когда он ей нужен);
- заголовок и ссылка на тикет, ключ тикета, имя автора обращения;
- для вопроса из pull request — имя ветки и репозитория.
Токен трекера не уходит никогда: запросы к трекеру делает коннектор изнутри вашей сети.
Если что-то не работает
| Симптом | Причина |
|---|---|
| бот молчит на упоминание | репозиторий или проект не в списке подключения; или обращение написано не к боту (проверьте имя учётной записи и псевдоним) |
| бот молчит на новые комментарии, старые тоже | подключение не запущено — посмотрите статус и журнал на локальной странице |
| ничего не происходит при назначении | назначение выключено по умолчанию — включите галочку в настройках подключения |
| вебхук не доходит | проверьте адрес приёмника у коннектора («по которому достучится трекер») и что порт доступен из трекера; опрос при этом продолжает работать |
| ответ приходит, но «по основной ветке» | репозиторий не подключён к Buff как источник кода — подключите его в разделе «Репозитории» |
| подключение не сохраняется: «dev_project … без организации» | в проекте разработки указана организация; нужно только имя проекта |