Jira
Data Center, Server и Cloud: две интеграции, их доступы, вебхуки и особенности.
Jira подключается интеграцией из каталога — как и любой другой трекер. Общее поведение (как обращаться, что бот пишет, область видимости, события) описано в «Интеграциях с трекерами»; здесь — только то, что относится именно к Jira.
Две интеграции, не одна
jira | jira-cloud | |
|---|---|---|
| Для чего | Jira Data Center и Server (self-hosted, включая старые версии) | Jira Cloud (*.atlassian.net) |
| Вход | Personal Access Token (Jira 8.14+) или логин и пароль (старее) | почта учётной записи + API-токен с id.atlassian.com |
| Комментарий | текст с разметкой Jira | документ (ADF): абзацы и упоминания — узлы, а не текст |
| Поиск | JQL, POST /rest/api/2/search | JQL, GET /rest/api/3/search/jql |
| Подпись вебхука | проверяется | Cloud не подписывает — пропуском служит секрет в ссылке |
| Страница витрины | /marketplace/jira | /marketplace/jira-cloud |
Разделять пришлось потому, что у Cloud другой API — вплоть до того, что привычный
POST /rest/api/2/search там отвечает «410 Gone». Одна интеграция «на всякий случай»
означала бы, что половина её кода не проверена ни на одной установке.
Настройка
Поставьте интеграцию из каталога и создайте подключение. Поля:
| Поле | jira | jira-cloud |
|---|---|---|
| Адрес | https://jira.corp.local (с контекстным путём, если он есть) | https://ваша-компания.atlassian.net |
| Ключи проектов | PROJ, OPS — те буквы, что стоят перед номером тикета | так же |
| Учётные данные | токен (или логин и пароль на старых версиях) | учётная запись (почта) и API-токен |
| Псевдоним | короткое имя бота, например buff | так же |
| Проект разработки | проект в Buff, куда попадают вопросы и задачи | так же |
Заведите боту отдельную учётную запись и дайте ей доступ только к нужным проектам: права учётной записи — внешняя граница, список ключей проектов — внутренняя. Прав на просмотр и комментирование достаточно; администратором бот быть не должен.
«Проверить связь» отвечает не «ок», а версией и редакцией вашей Jira и учётной записью, под которой агент вошёл, — чтобы было видно, что настроено именно то, что нужно.
Упоминание бота
Работают три формы:
- автодополнение Jira — вставит настоящее упоминание (ссылка и уведомление боту);
- просто текст
@buff— для Jira это обычный текст, но бот всё равно ответит; - команда через слэш —
/ask,/research,/task.
В Cloud у учётных записей нет логина: там обращаются к отображаемому имени («@Buff Bot») или к псевдониму из настройки. Регистр не важен.
Ссылка и документ в тикете
Jira умеет хранить ссылки отдельно от комментариев, и интеграция этим пользуется: ссылка на обсуждение или исследование в Buff попадает в блок ссылок тикета, а повторный ответ обновляет ту же ссылку, а не плодит дубликаты. Документ исследования прикладывается вложением к тикету — и в Data Center, и в Cloud, — так что его можно открыть и переслать, не заходя в Buff.
PDF из тикета и экспорт из приложения верстаются независимо и выглядят не одинаково. Содержание одно и то же. Каждая страница подписана колофоном — версией и коммитом кода, на котором готовилось исследование, — чтобы распечатанная копия оставалась опознаваемой.
Вебхуки
Опрос работает всегда; вебхук только ускоряет доставку. Общий порядок такой же, как у других трекеров, адрес в Jira: Администрирование → Система → Вебхуки → Создать вебхук. Отметьте «Issue updated» и «Comment created»; при желании сузьте охват JQL-фильтром по нужным проектам.
Data Center умеет подписывать вызовы, и коннектор эту подпись проверяет. Cloud не умеет — там пропуском служит секрет внутри выданной ссылки, поэтому её нельзя публиковать.
Если что-то не работает
| Симптом | Причина |
|---|---|
| «Не вышло: … personal access tokens» | Jira старше 8.14 — переключитесь на логин и пароль |
«Jira ответила 410» на интеграции jira | адрес ведёт в облако: там этого метода поиска больше нет — поставьте jira-cloud |
401 при верном токене в jira-cloud | не заполнена учётная запись: Cloud входит парой «почта + токен» |
| бот молчит на упоминание | проект не указан в ключах проектов подключения |
в разделе «Обзор» написано, что секция jira не используется | конфиг остался от версии со встроенной интеграцией — см. ниже |
Встроенная интеграция с Jira убрана. Раньше она настраивалась прямо в агенте,
секцией jira: в конфиге; теперь это интеграция из каталога. Агент с таким конфигом
стартует — секцию он сохраняет нетронутой, не использует и пишет об этом на
странице настроек, — но работать она перестала: подключение нужно создать заново.