# Интеграция с Jira

> Спрашивайте, запускайте исследования и заводите задачи прямо из тикета Jira — не отдавая нам доступ к вашей Jira.

Коннектор умеет не только переносить репозитории. Он подключает вашу **Jira** —
и тогда команда работает с Buff, не выходя из привычного тикета: упомянули бота
в комментарии, получили ответ там же.

_Иллюстрация: Обычный тикет: человек упомянул @buff, бот ответил в том же обсуждении._

Как и с git, **доступ к Jira остаётся у вас**. Токен лежит на машине, где
запущен агент, и к нам не попадает — агент ходит к Jira изнутри вашей сети.

## Что поддерживается

| | |
|---|---|
| **Jira Data Center** | да |
| **Jira Server** (обычный self-hosted, в том числе старые версии) | да |
| **Jira Cloud** | нет — там другой API и другая схема входа |

Способ входа агент выбирает **сам**, спросив вашу Jira о её версии:

| Версия Jira | Вход |
|---|---|
| 8.14 и новее | Personal Access Token |
| старше 8.14 | логин и пароль — токенов в этих версиях просто нет |

Если вы дадите токен старой Jira, мастер так и скажет, назвав найденную версию,
и предложит переключиться на логин с паролем. Гадать не придётся.

## Настройка

Настраивается всё **в самом коннекторе** — там же, где провайдеры git. Подойдёт
любой из трёх способов: [веб-интерфейс](/docs/connector/web-setup),
[терминал](/docs/connector/cli-setup) или [YAML](/docs/connector/yaml).

### Шаг 1. Доступ к Jira

Укажите адрес вашей Jira и токен, затем нажмите **«Проверить доступ»**.

_Иллюстрация: Base URL и токен. Токен записывается в локальный файл с правами 600 и никуда не уходит._

### Шаг 2. Проекты

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

_Иллюстрация: «Доступ есть ✓», версия и учётная запись — и проекты на выбор._

<Callout type="warn">
Отмеченные проекты — **и есть контроль доступа**. Внутри них звать бота может
любой, кто видит тикет. В неотмеченных проектах бот не отзовётся вообще.
</Callout>

Здесь же задаются:

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

Одна интеграция = один проект разработки. Если Jira одна, а проектов разработки
несколько — заведите несколько интеграций с разными наборами проектов Jira.

### Шаг 3. Как получать события

Два независимых способа, оба можно включать и выключать галочкой:

_Иллюстрация: Опрос работает всегда; вебхуки быстрее, но требуют доступного порта._

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

**Вебхуки** — Jira сама сообщает агенту об изменении. Отвечает быстрее, но нужен
порт, до которого Jira дотянется. Включив вебхуки, укажите:

- **Слушать на** — адрес и порт на этой машине (например `0.0.0.0:8766`);
- **Адрес, по которому Jira достучится сюда** — как этот порт виден со стороны
  Jira. Агент не может это угадать: за NAT или обратным прокси адрес другой.

<Callout type="warn">
Выключить оба способа нельзя — интеграция стала бы глухой, и мастер это не даст
сохранить.
</Callout>

### Шаг 4. Ссылка для вебхука

После сохранения интеграция появится в списке — с готовой ссылкой и кнопкой
**«Скопировать»**.

_Иллюстрация: Готовая ссылка: скопируйте её в настройки вебхука вашей Jira._

Вставьте её в Jira: **Администрирование → Система → Вебхуки → Создать вебхук**.
Отметьте события **«Issue updated»** и **«Comment created»**; при желании сузьте
охват JQL-фильтром по нужным проектам.

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

## Как пользоваться

### Упоминание в комментарии

Упомяните бота в комментарии и напишите, что нужно. Текст **вокруг** упоминания
тоже учитывается — можно сначала описать контекст, а потом попросить.

Упомянуть можно двумя способами, оба работают одинаково:

- **Через автодополнение Jira** — начните печатать `@` и выберите учётную запись
  бота. Jira вставит настоящее упоминание, оно выглядит ссылкой и бот получит
  уведомление. Так — на скриншоте выше.
- **Просто текстом** `@buff` — короче, но для Jira это обычный текст: ни ссылки,
  ни уведомления. Бот всё равно ответит.

| Что написать | Что произойдёт |
|---|---|
| `@buff почему падает экспорт?` | **вопрос** — бот разберётся в коде и ответит в тикете |
| `@buff research почему растёт задержка` | **исследование** — глубокий разбор, документ придёт сюда же |
| `@buff task починить экспорт CSV` | **черновик задачи** в Buff + ссылка на него |
| `@buff ask где лежит конфиг` | то же, что без команды — вопрос, только явно |

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

Повторное упоминание в том же тикете **продолжает тот же разговор**: можно
уточнять и переспрашивать, не начиная с нуля.

### Метки

Вместо упоминания можно повесить на тикет метку:

| Метка | Действие |
|---|---|
| `buff-research` | исследование |
| `buff-task` | черновик задачи |
| `buff-ask` | вопрос |

Тема тикета при этом и есть запрос. Метки срабатывают **в момент, когда их
вешают** — метка, которая уже висела, ничего не запускает. Поэтому включение
интеграции не приводит к лавине запусков по всем открытым тикетам.

Совпадение ищется по целым словам: `buff-task-urgent` сработает, `buff-tasks` —
нет.

### Назначение

Назначьте тикет на учётную запись бота — он возьмётся за него как за вопрос.
Как и с метками, срабатывает сам момент назначения.

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

1. **Сразу** — короткое «принял, работаю». Исследование идёт минутами, и без
   этого непонятно, услышал ли бот вообще.
2. **Ссылку** — на черновик, обсуждение или исследование в Buff. Она попадает в
   блок **Links** самого тикета, а не тонет в ленте комментариев. Повторный
   ответ обновляет ту же ссылку, а не плодит дубликаты.
3. **Результат** — готовый ответ или документ, комментарием.

Если что-то не получилось, бот об этом тоже напишет: молчание читалось бы как
поломка.

Статусы тикета бот **не трогает** — это ваш рабочий процесс, и лезть в него он
не должен.

## Что дальше

- `task` из Jira создаёт **черновик**, а не запускает разработку. Согласование
  формулировки — осознанный шаг, и он остаётся в Buff.
- Списания идут на **интеграцию**, а не на человека: пользователи вашей Jira —
  не пользователи Buff.

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

| Симптом | Причина |
|---|---|
| «Не вышло: … personal access tokens» | Jira старше 8.14 — переключитесь на логин и пароль |
| «Jira Cloud не поддерживается» | адрес ведёт в облачную Jira; нужна self-hosted |
| Бот молчит на упоминание | проект не отмечен галочкой в настройках интеграции |
| Бот молчит на метку | метка уже висела раньше — снимите и повесьте заново |
| Вебхук не доходит | проверьте «адрес, по которому Jira достучится сюда» и что порт открыт; опрос при этом продолжает работать |

Состояние интеграций видно там же, где вы их заводили — в
[веб-интерфейсе агента](/docs/connector/web-setup). Менять список проектов и
токен можно **на лету**, без перезапуска.