# Jira

> Data Center, Server и Cloud: две интеграции, их доступы, вебхуки и особенности.

Jira подключается интеграцией из каталога — как и любой другой трекер. Общее поведение
(как обращаться, что бот пишет, область видимости, события) описано в
[«Интеграциях с трекерами»](/docs/connector/trackers); здесь — только то, что
относится именно к 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) | [/marketplace/jira-cloud](/marketplace/jira-cloud) |

Разделять пришлось потому, что у Cloud другой API — вплоть до того, что привычный
`POST /rest/api/2/search` там отвечает «410 Gone». Одна интеграция «на всякий случай»
означала бы, что половина её кода не проверена ни на одной установке.

## Настройка

Поставьте интеграцию из [каталога](/docs/connector/marketplace) и создайте
подключение. Поля:

| Поле | `jira` | `jira-cloud` |
|---|---|---|
| Адрес | `https://jira.corp.local` (с контекстным путём, если он есть) | `https://ваша-компания.atlassian.net` |
| Ключи проектов | `PROJ, OPS` — те буквы, что стоят перед номером тикета | так же |
| Учётные данные | токен (или логин и пароль на старых версиях) | **учётная запись** (почта) **и** API-токен |
| Псевдоним | короткое имя бота, например `buff` | так же |
| Проект разработки | проект в Buff, куда попадают вопросы и задачи | так же |

_Иллюстрация: Форма строится по схеме, которую интеграция объявляет о себе: коннектор ничего не знает про поля Jira._

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

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

_Иллюстрация: Проверка связи: версия, редакция и от чьего имени агент вошёл._

## Упоминание бота

Работают три формы:

- **автодополнение Jira** — вставит настоящее упоминание (ссылка и уведомление боту);
- **просто текст** `@buff` — для Jira это обычный текст, но бот всё равно ответит;
- **команда через слэш** — `/ask`, `/research`, `/task`.

В Cloud у учётных записей нет логина: там обращаются к **отображаемому имени**
(«@Buff Bot») или к псевдониму из настройки. Регистр не важен.

## Ссылка и документ в тикете

Jira умеет хранить ссылки отдельно от комментариев, и интеграция этим пользуется:
ссылка на обсуждение или исследование в Buff попадает в блок ссылок тикета, а
повторный ответ **обновляет ту же ссылку**, а не плодит дубликаты. Документ
исследования прикладывается **вложением** к тикету — и в Data Center, и в Cloud, — так
что его можно открыть и переслать, не заходя в Buff.

<Callout>
PDF из тикета и экспорт из приложения верстаются независимо и выглядят не одинаково.
Содержание одно и то же. Каждая страница подписана колофоном — версией и коммитом
кода, на котором готовилось исследование, — чтобы распечатанная копия оставалась
опознаваемой.
</Callout>

## Вебхуки

Опрос работает всегда; вебхук только ускоряет доставку.
[Общий порядок](/docs/connector/trackers#события-опрос-и-вебхуки) такой же, как у
других трекеров, адрес в 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` не используется | конфиг остался от версии со встроенной интеграцией — см. ниже |

<Callout type="warn">
**Встроенная интеграция с Jira убрана.** Раньше она настраивалась прямо в агенте,
секцией `jira:` в конфиге; теперь это интеграция из каталога. Агент с таким конфигом
**стартует** — секцию он сохраняет нетронутой, не использует и пишет об этом на
странице настроек, — но работать она перестала: подключение нужно создать заново.
</Callout>