Интеграция Yandex Tracker

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

Кратко. Подключите Yandex Tracker к PanDev Metrics примерно за 10 минут. Вы создадите сервисный yandex-аккаунт с правами администратора в организации, выпустите OAuth-токен со scope-ами tracker:read и tracker:write, вставите его в Настройки → Интеграции → Yandex Tracker — PanDev Metrics сам зарегистрирует webhook на /v1/yandex/webhook/tracker. Аудитория: администратор.

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

• Запущенный PanDev Metrics (cloud-воркспейс или on-prem)
• yandex-аккаунт с правами администратора в нужной организации Yandex Tracker — обязательно, потому что PanDev Metrics создаёт webhook при подключении
• ID организации Yandex Tracker (находится в Администрирование → Настройки организации)
• Бэкенд PanDev Metrics доступен из Yandex Tracker по HTTPS — иначе webhook не дойдёт до /v1/yandex/webhook/tracker
• Роль администратора в PanDev Metrics для нужного тенанта

:::tip Сервисный аккаунт Заведите отдельный yandex-аккаунт, например pandev-metrics-bot@yandex.ru, и добавьте его в организацию Yandex Tracker с правами админа. Личные аккаунты тоже работают, но сервисный отделяет автоматическую вебхук-активность от истории людей и переживает увольнения. :::

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

Yandex Tracker требует, чтобы интеграционный пользователь состоял в организации и имел права администратора на тех очередях, которые планируется трекать. Права администратора нужны, потому что PanDev Metrics регистрирует webhook при подключении.

1. Войдите в tracker.yandex.ru под владельцем организации
2. Откройте Администрирование → Пользователи и пригласите сервисный yandex-аккаунт
3. В Администрирование → Роли выдайте сервисному пользователю роль Администратор организации
4. Убедитесь, что у пользователя есть доступ ко всем очередям, которые планируется синхронизировать (на уровне очереди права могут быть строже, чем на уровне организации)

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

PanDev Metrics аутентифицируется как сервисный пользователь по OAuth-токену. Токен должен иметь scope-ы tracker:read и tracker:write — запись нужна, чтобы PanDev Metrics мог пушить worklog-и на основе IDE.

1. Войдите в oauth.yandex.ru под сервисным аккаунтом
2. Нажмите Зарегистрировать новое приложение
3. Заполните форму:
   • Название — PanDev Metrics
   • Платформа — Веб-сервисы
   • Callback URI — https://oauth.yandex.ru/verification_code (стандартный для получения токена по verification code)
4. В Доступах добавьте:

Scope	Назначение
tracker:read	Чтение очередей, задач, комментариев, worklog-ов
tracker:write	Запись worklog для IDE-таймтрекинга

5. Сохраните приложение и откройте его
6. Пройдите device authorization flow или откройте в браузере под сервисным пользователем URL https://oauth.yandex.ru/authorize?response_type=token&client_id=<your-client-id>
7. Подтвердите доступ и скопируйте токен из URL-фрагмента

По умолчанию токен не истекает. Храните его в менеджере секретов.

Шаг 3 — Узнайте ID организации

PanDev Metrics нужен ID организации, чтобы скоупить API-вызовы к правильному тенанту Yandex Tracker.

1. Откройте tracker.yandex.ru под сервисным пользователем
2. Перейдите в Администрирование → Настройки организации
3. Скопируйте значение ID организации (число, например 7654321)

Cloud Organization (Yandex 360) и Yandex Cloud Organization используют разные форматы ID. PanDev Metrics принимает оба — вставьте значение ровно так, как оно показано.

Шаг 4 — Подключите Yandex Tracker в PanDev Metrics

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

1. Откройте PanDev Metrics и перейдите в Настройки → Интеграции → Yandex Tracker
2. Заполните форму:
   • ID организации — значение из Шага 3
   • OAuth-токен — значение из Шага 2
3. Нажмите Проверить подключение — PanDev Metrics проверит креды и покажет очереди, доступные сервисному пользователю
4. Отметьте очереди для мониторинга и нажмите Активировать

После активации PanDev Metrics регистрирует webhook на /v1/yandex/webhook/tracker для событий жизненного цикла задач и worklog-ов. Больше ничего в Yandex Tracker настраивать не нужно.

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

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

• Очереди — список ключей очередей для загрузки
• Фильтр задач — опционально, выражение фильтра Yandex Tracker, например Type: !Epic and Status: !Closed
• Режим worklog — автоматический пишет в Yandex Tracker время на основе IDE; read-only только читает существующие worklog-и
• Backfill истории — сколько дней исторических задач и worklog-ов подтянуть (по умолчанию 90 дней)

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

Проверка

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

Затем откройте любой дашборд с виджетом таск-трекера и убедитесь, что:

• Свежие задачи Yandex Tracker появились рядом с коммитами
• Статусы задач совпадают с Yandex Tracker (Open / In Progress / Resolved)
• IDE-время засчитывается задачам, чей ключ упоминается в именах веток или коммит-сообщениях (например, BACK-123)

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

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

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

Источник	Направление	Что хранится
Поля задачи	Pull + webhook	Key, summary, type, status, priority, assignee, author, queue, sprint, tags, components, story points, deadline
Переходы статусов	Webhook /v1/yandex/webhook/tracker	From, to, timestamp, actor — для cycle time и time-in-status
Worklog-и	Webhook + pull	Author, start, duration, issue key — обогащает IDE-таймтрекинг
Спринты	Pull	Sprint id, name, state, даты начала и окончания
Пользователи	Pull	Yandex id, display name, email — матчатся с сотрудниками PanDev Metrics

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

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

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

OAuth-токен неправильный, отозван или у него нет scope-ов tracker:read / tracker:write. Перевыпустите токен (Шаг 2) и вставьте в форму интеграции. Убедитесь, что сервисный пользователь всё ещё состоит в организации.

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

Сервисный пользователь состоит в организации, но не имеет роли Администратор на проверяемых очередях. Откройте Администрирование → Роли, выдайте админа, затем нажмите Синхронизировать сейчас в PanDev Metrics.

Подключение работает, но webhook-события не приходят

Сервера Yandex Tracker не могут достучаться до бэкенда PanDev Metrics на эндпойнте /v1/yandex/webhook/tracker. Бэкенд должен быть доступен по HTTPS из публичного интернета. С любого хоста вне вашей сети выполните curl -v https://<pandev-host>/v1/yandex/webhook/tracker — должен вернуться HTTP 4xx, а не ошибка соединения.

Worklog-и не появляются в Yandex Tracker после включения автоматического режима

У токена нет scope tracker:write. Перевыпустите токен с обоими scope-ами — tracker:read и tracker:write — и обновите его в Настройки → Интеграции → Yandex Tracker.

FAQ

Какие тарифы Yandex Tracker поддерживаются?

PanDev Metrics работает с любым тарифом Yandex Tracker — бесплатным и платным. Интеграция использует стандартный REST API и OAuth-flow, доступные на всех тарифах.

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

Сервисный пользователь должен иметь роль Администратор в организации Yandex Tracker. Права администратора нужны, потому что PanDev Metrics регистрирует webhook при подключении — у ролей ниже на это нет полномочий. Доступ к очередям должен быть выдан на каждой синхронизируемой очереди.

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

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

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

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

Будет ли PanDev Metrics писать в Yandex Tracker?

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

Сколько живёт OAuth-токен?

По умолчанию OAuth-токены Yandex не истекают. Они валидны, пока вы не отзовёте приложение в oauth.yandex.ru. Если в организации задана политика истечения, перевыпустите токен до окончания срока и обновите его в Настройки → Интеграции → Yandex Tracker.

Можно ли подключить несколько организаций Yandex Tracker?

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

Есть ли rate limit?

Yandex Tracker применяет глобальные лимиты на запросы по организации. PanDev Metrics автоматически замедляет свои вызовы и уходит на webhook-обновления при приближении к лимиту. Большие backfill-ы (свыше 100k задач) могут идти несколько часов вместо минут.

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

• Установите JetBrains-плагин — захват IDE-времени по задачам Yandex Tracker
• Установите VS Code плагин — то же для VS Code, Cursor и Windsurf
• Подключите GitLab — связь коммитов и merge request с задачами Yandex Tracker

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

• Интеграция Jira — альтернативный таск-трекер
• Notion как таск-трекер — лёгкий вариант
• Интеграция GitHub — полная картина git ↔ tracker ↔ IDE