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

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

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

Кратко. Гайд включает Azure Boards как таск-трекер в PanDev Metrics примерно за 10 минут. Azure Boards живёт в той же организации Azure DevOps, что и Azure Repos с Pipelines, — вы используете тот же Personal Access Token (с Work Items: Read), открываете Настройки → Интеграции → Azure DevOps и убеждаетесь, что work items Boards появляются на дашбордах. Аудитория: администратор.

:::tip Один экран на всю интеграцию Azure Boards — часть более широкой интеграции Azure DevOps. Если Azure Repos или Pipelines уже подключены, Azure Boards включится тем же PAT — нужно только наличие scope Work Items: Read. Если Azure DevOps уже подключён, переходите сразу к Шагу 3. :::

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

  • Запущенный PanDev Metrics (Cloud-воркспейс или on-prem)
  • Доступ администратора к воркспейсу PanDev Metrics
  • Пользователь Azure DevOps (желательно сервисный) с правами Project Administrator в проектах Boards, которые нужно анализировать
  • Для on-prem PanDev Metrics: исходящий 443 до dev.azure.com или хоста Azure DevOps Server
  • Чтобы Azure DevOps мог достучаться до on-prem PanDev Metrics: хост PanDev Metrics должен быть доступен из Azure DevOps по публичному webhook URL

Шаг 1 — Создайте или обновите PAT Azure DevOps​

Boards использует тот же PAT, что и Repos с Pipelines. Убедитесь, что включены следующие scope'ы:

ScopeУровеньЗачем
Work ItemsReadПеречисление, чтение и webhook'и work items
CodeReadСвязь work items с коммитами и PR (если Repos тоже отслеживаются)
Project and TeamReadПеречисление проектов, видимых PAT

Если вы уже выпустили PAT для Azure DevOps, проверьте, включён ли Work Items: Read. Если нет — перевыпустите PAT с этим scope'ом и обновите его в PanDev Metrics.

:::warning Сохраните PAT сразу Azure DevOps показывает PAT ровно один раз. Положите его в менеджер секретов. :::

Шаг 2 — Откройте экран интеграции Azure DevOps​

Войдите в PanDev Metrics как администратор воркспейса и откройте Настройки → Интеграции → Azure DevOps. Отдельной карточки Azure Boards нет — Boards относится к интеграции Azure DevOps.

Если Azure DevOps ещё не подключён, заполните Organization URL и Personal access token, нажмите Check connection, затем Activate — полный гайд: Интеграция Azure DevOps.

Шаг 3 — Включите синхронизацию Boards в PanDev Metrics​

После того как Azure DevOps подключён:

  1. Откройте Настройки → Интеграции → Azure DevOps → Advanced.
  2. Включите Sync Azure Boards work items.
  3. Выберите проекты Boards для синхронизации (может быть подмножеством списка проектов Repos).
  4. Сохраните.

PanDev Metrics запускает одноразовый backfill за последние 90 дней по work items, переходам состояний и worklog'у.

Шаг 4 — Проверьте service hooks для Boards​

PanDev Metrics регистрирует service hooks Azure DevOps для Boards автоматически. Чтобы убедиться, откройте Project settings → Service hooks в Azure DevOps. Должны быть хуки Work item created, Work item updated, Work item commented on и Work item deleted, указывающие на /v1/azure/webhook/boards на хосте PanDev Metrics.

Последние доставки должны возвращать HTTP 200 в течение секунд.

Проверка​

Откройте Настройки → Интеграции → Azure DevOps в PanDev Metrics. Вы увидите:

  • Зелёный бейдж Подключено
  • Количество выбранных проектов Boards в разделе Azure Boards
  • Время последней синхронизации (не старше 30 минут после backfill)

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

  • Свежие work items Boards появляются рядом с коммитами
  • Состояния соответствуют Azure Boards (New / Active / Resolved / Closed плюс ваши кастомные)
  • Items связаны с коммитами и PR через стандартное упоминание #1234 в сообщениях коммитов и заголовках PR

Для принудительного обновления нажмите Sync now на плитке интеграции.

Что синхронизируется​

PanDev Metrics получает узкий срез данных Azure Boards.

ИсточникНаправлениеЧто сохраняется
Поля work itemPull + webhookID, заголовок, тип (User Story / Bug / Task / Epic / …), state, area path, iteration path, assignee, теги, приоритет, story points
Переходы состоянийWebhook /v1/azure/webhook/boardsОт, к, время, actor — для cycle time и time-in-state
Итерации (спринты)PullID итерации, имя, даты старта/конца, area path
ПользователиPullAzure DevOps user id, имя, email — сопоставляются с сотрудниками PanDev Metrics

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

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

Service hooks зарегистрированы, но события Boards не приходят

PAT без scope Work Items: Read. Пересоздайте PAT с этим scope'ом и обновите его в Настройки → Интеграции → Azure DevOps → Advanced → Update token. События Boards возобновятся в течение минут.

Backfill прошёл, но переходы состояний показаны как «Unknown»

У сервисного аккаунта нет права View work items in this node на части area paths. Откройте Project settings → Permissions в Azure DevOps, выдайте пользователю (или его группе) права на чтение нужных area paths, затем нажмите Sync now.

Кастомные типы work item не синхронизируются

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

Work items не связаны с коммитами / PR

Azure DevOps связывает код с Boards через упоминание #1234 в сообщениях коммитов и описаниях PR. Автор коммита должен быть тем же лицом, что и пользователь Azure DevOps (или связан с ним). Если связи нет — убедитесь, что команда пишет #<work-item-id> в коммитах и PR.

Azure DevOps Server возвращает 404 на API Boards

Для Server URL организации должен включать collection: https://azuredevops.acme.example/DefaultCollection. Без сегмента collection REST API отвечает 404. Обновите URL в Настройки → Интеграции → Azure DevOps.

FAQ​

Нужен ли отдельный токен или экран для Azure Boards?​

Нет. Azure Boards входит в интеграцию Azure DevOps — один PAT и один экран настройки покрывают Repos, Pipelines и Boards. Главное — включить Work Items: Read в PAT.

Какие минимальные scope'ы PAT для use case'а только Boards?​

Work Items: Read + Project and Team: Read. Если нужны только Boards (без Repos/Pipelines) — включите эти два scope'а. Уровень Project Administrator в Azure DevOps всё равно нужен, чтобы PanDev Metrics мог зарегистрировать service hooks.

Работает ли PanDev Metrics с Azure DevOps Server?​

Да. Тот же PAT-флоу работает на Server. URL организации должен содержать collection (например https://azuredevops.acme.example/DefaultCollection). Для on-prem PanDev Metrics нужен сетевой доступ к Server-хосту по 443.

Как часто обновляются данные Boards?​

Service hooks доставляют события work item в реальном времени — обычно за секунды. PanDev Metrics дополнительно раз в 15 минут запускает реконсиляцию для пропущенных доставок.

Можно ли связать коммиты и PR с work items?​

Да. Добавьте #<work-item-id> (стандарт Azure DevOps) в сообщения коммитов и заголовки PR. Azure DevOps создаёт связь в своём UI, PanDev Metrics наследует ту же связь.

Пишет ли PanDev Metrics в Azure Boards?​

Только worklog в режиме automatic worklog — PanDev пишет IDE-время в поле Completed Work связанного work item. В режиме read-only записи нет.

Можно ли синхронизировать только часть проектов Boards?​

Да. В Настройки → Интеграции → Azure DevOps → Advanced выберите только нужные проекты Boards. Выбор не зависит от списка проектов Repos / Pipelines.

Сколько идёт первичный backfill?​

PanDev Metrics при включении Boards подтягивает последние 90 дней work items. Для 5k items это занимает 5-15 минут; очень крупные проекты (50k+ items) — час и больше.

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

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