# Интеграции с трекерами

> Как команда работает с ботом в своём трекере: обращения, команды, область видимости, ветка 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 …` | то же, что без команды — вопрос, только явно |

Без команды это **вопрос**: самый частый случай и потому умолчание.

<Callout>
`task` создаёт **черновик**, а не запускает разработку. Согласование формулировки —
осознанный шаг, и он остаётся в Buff.
</Callout>

## Область видимости — это контроль доступа

У каждого подключения есть список: репозитории или ключи проектов, где бот работает.
Список действует **в обе стороны** — в неотмеченных местах бот не читает обращения и
не пишет ответы.

<Callout type="warn">
Пустой список означает **«нигде»**, а не «везде». Подключение без явно указанных
репозиториев или проектов не отвечает нигде — это защита от «поставил и забыл
настроить область».
</Callout>

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

## Ответ по коду того места, где спросили

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

| Где спросили | На каком коде считается ответ |
|---|---|
| задача / тикет | код проекта разработки, к которому привязано подключение |
| pull request / merge request | **ветка этого pull request** |
| комментарий к коммиту | ветка, на которую указывает событие; иначе — основная |

Чтобы это работало, репозиторий должен быть подключён к Buff **как источник кода** —
тем же коннектором, в разделе «Репозитории». Если он не подключён, бот всё равно
ответит по основной ветке проекта и **прямо скажет об этом в тикете**: ответ,
посчитанный по другому коду и выданный за ответ на этот pull request, хуже, чем
никакого.

## Что бот пишет в тикет

1. **Сразу** — короткое «принял, работаю»: исследование идёт минутами, и без этого
   непонятно, услышал ли бот вообще.
2. **Ссылку** — на обсуждение, черновик или исследование в Buff. Там, где трекер умеет
   хранить ссылки отдельно (Jira), она попадает в блок ссылок тикета, а не тонет в
   ленте комментариев.
3. **Результат** — готовый ответ комментарием. Для исследования — ещё и сам документ:
   там, где трекер принимает вложения, PDF прикладывается к тикету.

Если данных не хватает, бот **задаст уточняющий вопрос в том же тикете** и дождётся
ответа. Если что-то не получилось — тоже напишет: молчание читалось бы как поломка.

**Статусы, метки, исполнителей и поля бот не трогает никогда.** Ни одна трекерная
интеграция не имеет для этого инструмента: единственный пишущий инструмент —
комментарий, и [модели он не отдаётся](/docs/connector/tools#пишущие-инструменты-не-отдаются-модели-никогда).

## Назначение задачи боту

Назначение — пограничный случай: задача действительно адресована боту, но назначают и
по правилам маршрутизации, когда работу никто не заказывал. Поэтому оно **выключено по
умолчанию** и включается галочкой **«Принимать задачи, назначенные боту»** — если у вас
назначает человек осознанно.

## События: опрос и вебхуки

**Опрос работает всегда.** Каждое подключение читает свой трекер раз в 20 секунд, и
для этого не нужно открывать наружу ни одного порта — соединение исходящее. Для
закрытого периметра это рабочий режим по умолчанию.

**Вебхуки только ускоряют доставку.** Приёмник принадлежит коннектору — один адрес на
все подключения, настраивается в разделе
[«Подключение»](/docs/connector/web-setup#подключение). У самого подключения есть
только выключатель: **ссылку с секретом выдаёт коннектор**, придумывать её не нужно.

_Иллюстрация: У подключения — выключатель; ссылку для трекера выдаёт коннектор._

<Callout type="warn">
Эта ссылка **сама по себе пароль**: в ней зашит секрет. Не публикуйте её. Там, где
трекер умеет подписывать свои вызовы, коннектор проверяет ещё и подпись — своим
алгоритмом для каждого трекера. Секрет переживает переименование подключения, так что
ссылку не придётся менять.
</Callout>

Куда вставлять ссылку и на какие события подписываться:

| Трекер | Где | События |
|---|---|---|
| **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`](/docs/connector/jira) (DC, Server) | да | — | — | `PROJ-7` | да, с подписью |
| [`jira-cloud`](/docs/connector/jira) | да | — | — | `PROJ-7` | да, секрет в ссылке |
| [`gitea`](/marketplace/gitea) (+ Forgejo) | да | да | — | `acme/api#7` | да, с подписью |
| [`gitlab`](/marketplace/gitlab) (self-hosted и gitlab.com) | да | да | да | `group/app#7`, `!7`, `@sha` | да, с проверкой токена |
| [`github`](/marketplace/github) (+ Enterprise Server) | да | да | да | `acme/api#7`, `acme/api@sha` | да, с подписью |
| [`bitbucket-dc`](/marketplace/bitbucket-dc) | — | да | — | `ACME/api!7` | да, с подписью |
| [`bitbucket-cloud`](/marketplace/bitbucket-cloud) | да, где включён трекер репозитория | да | — | `acme/api!7`, `#7` | да, секрет в ссылке |
| [`redmine`](/marketplace/redmine) | да | — | — | `catalog#7` | нет |

Кроме трекеров в каталоге есть **источники знаний** — Confluence: там бот не ведёт
задачи, а читает написанное командой и отвечает в обсуждении страницы. Отдельная
страница: [«Источники знаний»](/docs/connector/knowledge).

У Bitbucket Data Center **своего трекера задач нет** — интеграция живёт в pull request.
Если задачи у вас в Jira или Redmine, поставьте рядом их интеграцию: подключений может
быть сколько угодно, и у каждого свой проект разработки.

## Что уходит к нам из трекера

Только то, без чего запрос не выполнить, и только по прямому обращению:

- текст обращения (без остального содержимого тикета — его модель читает инструментом,
  когда он ей нужен);
- заголовок и ссылка на тикет, ключ тикета, имя автора обращения;
- для вопроса из pull request — имя ветки и репозитория.

Токен трекера не уходит **никогда**: запросы к трекеру делает коннектор изнутри вашей
сети.

## Если что-то не работает

| Симптом | Причина |
|---|---|
| бот молчит на упоминание | репозиторий или проект не в списке подключения; или обращение написано не к боту (проверьте имя учётной записи и псевдоним) |
| бот молчит на **новые** комментарии, старые тоже | подключение не запущено — посмотрите статус и журнал на локальной странице |
| ничего не происходит при назначении | назначение выключено по умолчанию — включите галочку в настройках подключения |
| вебхук не доходит | проверьте адрес приёмника у коннектора («по которому достучится трекер») и что порт доступен из трекера; опрос при этом продолжает работать |
| ответ приходит, но «по основной ветке» | репозиторий не подключён к Buff как источник кода — подключите его в разделе «Репозитории» |
| подключение не сохраняется: «dev_project … без организации» | в проекте разработки указана организация; нужно только имя проекта |