Jira

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

• Вопрос по коду, не выходя из тикета

  Тестировщик завёл тикет «экспорт в CSV ломается на кириллице» и не знает, где копать. Он упоминает бота в комментарии и просит разобраться.

  Результат. Через несколько минут в тикете лежит разбор: где формируется выгрузка, почему теряется кодировка и что придётся менять. Никто не заводил задачу и не переключался в другой интерфейс.

• Задача разработки прямо из тикета

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

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

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

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

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

• Ответ там, где его ждут

  Заказчик задачи не заходит в интерфейс Buff и не собирается. Ему нужен ответ в тикете, который он открыл.

  Результат. Готовый разбор или ссылка на pull request приходит комментарием в исходный тикет. Единственный инструмент интеграции, который что-то пишет, — и он недоступен на стадиях, где модель только читает.

1. @buff, найди в истории тикеты по проблеме кеширования

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

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

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

2. @buff, разберись, почему при экспорте в CSV ломается кириллица

   комментарий в самом тикете с проблемой

   инструмент: get_issue + инструменты по коду

   Прочитал тикет целиком, вместе с обсуждением, и разобрал по коду. Выгрузка собирается в ExportService.buildCsv, файл отдаётся без BOM и с заголовком text/csv без charset — Excel в Windows читает такой файл в cp1251. Разбор с местами в коде приложил документом и продублировал ссылкой сюда.

3. @buff, заведи по этому тикету задачу разработки

   комментарий в тикете

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

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

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

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

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

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

5. @buff, что уже обсуждали в этом тикете?

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

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

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

1. Шаг 1

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

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

   Коннектор

   

2. Шаг 2

   Настройка — форма из самой интеграции

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

   Коннектор

   

3. Шаг 3

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

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

4. Шаг 4

   Версия подключения не меняется сама

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

5. Шаг 5

   Машина без интернета

   Если у машины нет выхода наружу вообще, каталог и бандлы переносятся файлами: подписанный комплект собирается там, где сеть есть, и кладётся на носитель. Проверка подписи при установке та же самая — именно ради такого переноса она и нужна. Как вариант, весь реестр можно зеркалировать к себе в Harbor или Nexus и указать коннектору на зеркало.

6. Шаг 6

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

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

   Коннектор

   

7. Шаг 7

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

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

   Коннектор

   

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

• Jira Data Center или self-hosted Server. Jira Cloud пока не поддерживается.
• Personal Access Token (Jira 8.14 и новее) или логин с паролем для старых Server.
• Сетевой доступ от машины с коннектором до Jira — наружу из вашей сети ничего открывать не нужно.
• Коннектор, запущенный с правом заводить отдельного пользователя ОС для интеграции (root или CAP_SETUID).

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

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

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

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

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

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

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

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

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

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

Как обновляется интеграция?

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

А если наша система умеет только присылать вебхук и опрашивать её нечем?

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

Как быстро приходит ответ на упоминание в тикете?

Без приёма событий — в пределах интервала опроса, это секунды-десятки секунд до того, как запрос будет принят; сам ответ занимает столько, сколько занимает работа. С включённым приёмом запрос принимается почти сразу, как только трекер прислал вызов.

Может ли бот ответить на один и тот же вопрос дважды?

Нет. У каждого события свой идентификатор, коннектор сдвигает отметку прочитанного только за доставленными событиями, а платформа отклоняет повторы. Перезапуск агента или обрыв связи не превращаются во второй ответ.

А если у машины нет выхода в интернет?

Работает. Каталог и бандлы можно перенести файлами подписанным комплектом или зеркалировать наш реестр в свой Harbor либо Nexus. Подпись проверяется в любом случае — ради такого переноса она и существует.