Перейти к основному содержимому
Версия: v2 (текущая)

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

import IdealImage from "@theme/IdealImage"; import Head from "@docusaurus/Head";

Кратко. Подключите Jira Cloud, Server или Data Center к PanDev Metrics примерно за 10 минут. Вы создадите отдельный jira-аккаунт с правами администратора, выпустите токен, вставите его в Настройки → Интеграции → Jira — PanDev Metrics сам зарегистрирует webhooks. Аудитория: администратор.

Что понадобится​

  • Запущенный PanDev Metrics (cloud-воркспейс или on-prem)
  • jira-аккаунт с правами администратора и доступом к нужным проектам — права администратора нужны, потому что PanDev Metrics создаёт webhooks при подключении
  • URL Jira Cloud (https://your-domain.atlassian.net) или базовый URL Jira Server / Data Center, доступный с бэкенда PanDev Metrics
  • Бэкенд PanDev Metrics доступен из jira (Cloud → публичный URL, on-prem → маршрутизируемый хост) — иначе webhooks не дойдут до /v1/jira-worklog и /v1/issue/**
  • Роль администратора в PanDev Metrics для нужного тенанта

:::tip Сервисный аккаунт Заведите отдельный jira-аккаунт, например pandev-metrics-bot. Личные аккаунты тоже работают, но сервисный отделяет автоматическую активность (worklog, вебхуки) от истории людей и переживает увольнения. :::

Шаг 1 — Подготовьте jira-аккаунт​

PanDev Metrics нужны права уровня администратора в jira — потому что при подключении регистрируются webhooks и читаются worklog-и по всем выбранным проектам.

Для Jira Cloud: пригласите сервисного пользователя в Atlassian-организацию с ролью Org admin или site admin, затем добавьте его в проекты, которые планируете трекать.

Для Jira Server / Data Center: в Administration → User management заведите пользователя и добавьте его в группу с глобальным правом Jira Administrators.

Выдайте проектные права Browse Projects, View Development Tools, Work On Issues на каждом проекте, который будет синхронизироваться.

Шаг 2 — Выпустите токен jira​

PanDev Metrics аутентифицируется как сервисный пользователь по токену. Тип токена зависит от вкуса jira.

Jira Cloud — API token​

  1. Войдите в Atlassian под сервисным аккаунтом
  2. Откройте id.atlassian.com → Security → API tokens
  3. Нажмите Create API token
  4. Введите имя, например pandev-metrics
  5. Нажмите Create и сразу скопируйте токен — Atlassian показывает его только один раз

Jira Server / Data Center — Personal Access Token​

  1. Войдите в jira под сервисным аккаунтом
  2. Откройте Profile → Personal Access Tokens
  3. Нажмите Create token
  4. Укажите имя и срок действия (один год — нормальный дефолт)
  5. Нажмите Create и сохраните токен

Шаг 3 — Подключите jira в PanDev Metrics​

PanDev Metrics сохраняет креды внутри тенанта и регистрирует webhooks в jira во время этого шага.

  1. Откройте PanDev Metrics и перейдите в Настройки → Интеграции → Jira
  2. Выберите Jira Cloud или Jira Server / Data Center
  3. Заполните форму подключения:
    • Jira URL — https://your-domain.atlassian.net для Cloud или полный базовый URL для Server / Data Center
    • Email — почта сервисного аккаунта (только Cloud)
    • Token — значение из Шага 2
  4. Нажмите Проверить подключение — PanDev Metrics проверит креды, получит список проектов и покажет те, что доступны сервисному пользователю
  5. Отметьте проекты для мониторинга и нажмите Активировать

После активации PanDev Metrics регистрирует webhooks на /v1/jira-worklog (события worklog) и /v1/issue/** (события жизненного цикла задач). Больше ничего в jira настраивать не нужно.

Шаг 4 — Выберите, что синхронизировать​

Настройте, какие данные попадают в PanDev Metrics, чтобы дашборды оставались сфокусированными.

  • Проекты — список ключей проектов для загрузки
  • JQL-фильтр — опционально, например type != Epic AND statusCategory != Done, чтобы исключить родительские элементы
  • Режим worklog — автоматический пишет в jira оценки на основе IDE; read-only только читает существующие worklog-и, ничего не пишет
  • Backfill истории — сколько дней исторических задач и worklog-ов подтянуть (по умолчанию 90 дней)

Сохраните форму. Первый backfill идёт в фоне, обычно завершается за 10-30 минут для средних проектов.

Проверка​

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

Дальше откройте любой дашборд с виджетом таск-трекера (например, DORA → Lead time for changes) и убедитесь, что:

  • Свежие jira-задачи появились рядом с коммитами
  • Статусы задач совпадают с jira (To Do / In Progress / Done)
  • IDE-время засчитывается задачам, чей ключ упоминается в именах веток или коммит-сообщениях (например, PDM-123)

Для принудительного опроса нажмите Синхронизировать сейчас на плитке интеграции.

Какие данные собираются​

PanDev Metrics забирает ограниченный, чётко определённый срез данных jira — без исходного кода, без тел комментариев по умолчанию.

ИсточникНаправлениеЧто хранится
Поля задачиPull + webhookKey, summary, type, status, status category, priority, assignee, reporter, project, sprint, labels, components, story points, due date
Переходы статусовWebhook /v1/issue/**From, to, timestamp, actor — для cycle time и time-in-status
Worklog-иWebhook /v1/jira-worklog + pullAuthor, started, time spent, issue key — обогащает IDE-таймтрекинг
СпринтыPullSprint id, name, state, даты начала и окончания
ПользователиPullAccount id, display name, email — матчатся с сотрудниками PanDev Metrics

Код, вложения и тела комментариев не хранятся.

Решение проблем​

«Проверить подключение» возвращает `401 Unauthorized`

Токен неправильный, просрочен или принадлежит другому аккаунту. Перевыпустите токен (Шаг 2), вставьте его без пробелов по краям, для Cloud убедитесь, что email совпадает с аккаунтом, который создавал API token.

Подключение работает, но задачи не появляются 30 минут

У сервисного пользователя нет права Browse Projects на выбранных проектах. Откройте админку jira, проверьте права проектов, затем вернитесь в Настройки → Интеграции → Jira и нажмите Синхронизировать сейчас.

Webhook-события не приходят (Jira Server / Data Center)

Хост jira не может достучаться до бэкенда PanDev Metrics на эндпойнтах /v1/jira-worklog и /v1/issue/**. С хоста jira выполните curl -v https://<pandev-host>/v1/jira-worklog — должен вернуться HTTP 4xx, а не ошибка соединения. Откройте firewall между jira и PanDev Metrics на порт 443.

Дубли worklog-ов в jira после включения автоматического режима

Так бывает, если jira-плагин tempo (или похожий) и PanDev Metrics пишут одни и те же интервалы. Переключите режим worklog в read-only или отключите конфликтующий плагин для интеграционного пользователя.

FAQ​

Cloud vs Server / Data Center — что выбирать?​

PanDev Metrics поддерживает все три варианта одинаково. Выбирайте по тому, где уже живёт ваша jira — разницы в функционале нет. Cloud использует email + API token, Server / Data Center — Personal Access Token, webhooks регистрируются одинаково.

Какие минимальные права в jira?​

Нужен jira-аккаунт администратора с доступом к нужным проектам. Права администратора обязательны, потому что PanDev Metrics регистрирует webhooks при подключении — у ролей ниже на это нет полномочий. Внутри проектов пользователю нужны Browse Projects, View Development Tools, Work On Issues.

Как работает синхронизация worklog?​

PanDev Metrics читает существующие worklog-и jira и, если включён автоматический режим, пишет обратно время, собранное IDE-плагинами. Время прикрепляется к задаче, чей ключ найден в имени ветки, коммит-сообщении или контексте IDE. События worklog приходят почти в реальном времени через webhook /v1/jira-worklog.

Можно ли связать коммиты и PR с задачами jira?​

Да. Укажите ключ задачи (например, PDM-123) в имени ветки, коммит-сообщении или заголовке pull request. Git-интеграция извлекает ключ, PanDev Metrics джойнит его с данными jira, и задача появляется рядом с коммитом на дашборде. Так PanDev Metrics строит вью «стоимость фичи».

Будет ли интеграция писать в jira?​

Только если режим worklog — автоматический. В режиме read-only PanDev Metrics ничего не пишет: только читает задачи, worklog-и и webhook-события. Большинство команд начинает с read-only и включает автоматический worklog после того, как доверится IDE-таймтрекингу.

Нужен ли webhook на каждый проект?​

Нет. PanDev Metrics регистрирует один набор webhooks на уровне инстанса jira. Добавление или удаление проектов в Настройки → Интеграции → Jira не трогает webhooks — меняется только фильтр проектов на стороне PanDev Metrics.

Что будет, если токен протухнет?​

Плитка интеграции станет красной, а Проверить подключение вернёт 401. Сгенерируйте новый токен (Шаг 2), вставьте в форму интеграции и нажмите Сохранить. Существующие данные сохраняются — приостанавливается только приём новых событий.

Можно ли подключить несколько инстансов jira к одному тенанту?​

Да. Добавьте каждый инстанс отдельно в Настройки → Интеграции → Jira → Добавить инстанс. PanDev Metrics держит ключи проектов уникальными внутри инстанса — одинаковые ключи в разных jira не конфликтуют.

Дальнейшие шаги​

Связанные материалы​