Confluence

Половина ответов на вопросы «почему так» уже написана — в Confluence. Требования, архитектурные решения, регламенты, ранбуки: то, что человек не станет пересказывать в вопросе и чего модель сама не знает. Интеграция даёт Buff читать отмеченные пространства, когда это нужно для ответа, и принимает вопросы прямо в обсуждении страницы. Одна интеграция работает и с self-hosted (Data Center, Server), и с Cloud.

• Ответ по коду с оглядкой на регламент

  Разработчик спрашивает, как правильно оформить выпуск. В коде этого нет: схема нумерации, сроки и кто дежурит записаны в Confluence, и половина команды помнит их неточно.

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

• Требования, до которых никто не долистал

  Задача сформулирована в трекере одной строкой, а настоящие требования лежат в вики: три страницы обсуждения и таблица ограничений, о которой автор задачи забыл.

  Результат. Отвечая на вопрос по задаче, модель сама заглядывает в отмеченные пространства и находит ограничения раньше, чем они всплывут на ревью.

• Вопрос прямо на странице

  Кто-то читает регламент и не понимает, как он применяется к их случаю. Идти в другой инструмент ради вопроса — лишний шаг, который обычно не делают.

  Результат. Он упоминает бота в комментарии к странице. Ответ приходит туда же, в то же обсуждение, и остаётся рядом с текстом, о котором спрашивали.

• Ранбук вместо расспросов дежурного

  Инцидент ночью, дежурный новый, а порядок действий описан в вики — в разделе из пяти страниц.

  Результат. Бот собирает ответ из нужных страниц раздела и отвечает по существу, со ссылками на каждую. Дежурный читает три абзаца вместо пяти страниц.

1. @buff как у нас принято нумеровать релизы?

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

   инструмент: search_pages + get_page

   По схеме ГГ.ММ.N — год, месяц и порядковый номер релиза в месяце; внутреннее имя схемы «Гринвич». Выпуск в четверг, решение о переносе принимает дежурный. Источник: страница «Регламент выпуска релизов» в пространстве DOC.

2. @buff какие ограничения мы записали по интеграции с внешним API?

   вопрос в приложении Buff или комментарий на странице

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

   Нашёл три страницы: «Интеграция с внешним API» (лимит 100 запросов в минуту и обязательная идемпотентность), «Решение по ретраям» (экспоненциальная задержка, максимум 5 попыток) и обсуждение, где договорились не хранить ответы дольше суток. Ссылки на все три — ниже.

3. /research почему мы отказались от общего кеша

   комментарий на странице с решением

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

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

4. @buff что в этом разделе есть про резервные копии?

   комментарий на родительской странице раздела

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

   В разделе четыре дочерние страницы; про резервные копии — две: «Резервное копирование» (расписание, срок хранения 90 дней) и «Восстановление» (порядок и кто утверждает). Обе — по ссылкам.

1. Шаг 1

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

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

   Коннектор

   

2. Шаг 2

   Настройка — адрес, доступ и список пространств

   Для self-hosted адрес такой: `https://wiki.corp.local`; для Cloud — `https://ваша-компания.atlassian.net/wiki`. Дальше учётные данные бота (у Cloud — почта и API-токен) и ключи пространств: их видно в адресе страницы, `/spaces/DOC/pages/…`. Секрет хранится на вашей машине; интеграция его не видит.

   Коннектор

   

3. Шаг 3

   Заведите боту отдельную учётную запись

   Дайте ей доступ на чтение только к тем пространствам, где он должен работать, и право комментировать. Администратором Confluence бот быть не должен: всё, что ему нужно, — читать страницы и оставлять комментарии.

4. Шаг 4

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

   Установка без графики равноправна, а не запасной вариант: `connector install confluence`, затем `connector instance add confluence --config base_url=https://wiki.corp.local --config spaces=DOC,OPS`.

5. Шаг 5

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

   Опрос работает всегда и портов не требует: интеграция сама раз в 20 секунд читает комментарии отмеченных пространств. Если у вас Data Center и хочется быстрее — включите приём событий у коннектора и добавьте вебхук: он не разбирается по содержимому, а просто будит опрос, поэтому ответ приходит сразу, а не в следующий проход.

   Коннектор

   

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

• Confluence Data Center, Server или Cloud — одна и та же интеграция.
• Учётная запись бота с правом читать нужные пространства и комментировать: токен для self-hosted, почта и API-токен для Cloud.
• Сетевой доступ от машины с коннектором до Confluence — наружу из вашей сети ничего открывать не нужно.
• Коннектор, запущенный с правом заводить отдельного пользователя ОС для интеграции (root или CAP_SETUID).
• Задачи и код подключаются отдельно: Confluence — источник знаний, а не трекер и не репозиторий.

Вы скопируете нашу базу знаний к себе?

Нет. Интеграция читает страницы по запросу модели, когда ответ этого требует, и ничего не переносит и не индексирует заранее. Прочитанное попадает в контекст конкретного ответа — не в хранилище.

У нас Cloud, а не Data Center. Нужна другая интеграция?

Нет, эта же. Мы проверили на живых серверах обеих редакций: в том, что нужно интеграции, их API совпадает. Отличается вход — у Cloud это почта и API-токен, и в форме подключения для этого есть отдельное поле. Адрес для Cloud указывайте вместе с `/wiki`: `https://ваша-компания.atlassian.net/wiki`.

Бот сможет что-то изменить на страницах?

Нет. Он читает страницы и пишет комментарии; создавать и править страницы он не умеет — такого инструмента у интеграции нет вовсе.

Как ограничить, что он видит?

Двумя способами сразу: правами учётной записи бота в Confluence и списком пространств в настройке подключения. Список работает в обе стороны, а пустой список означает «нигде», а не «везде».

Большая страница — это большой счёт?

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