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

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

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

Кратко. Гайд подключает Bitbucket к PanDev Metrics примерно за 10 минут. Для Bitbucket Cloud вы создадите app password; для Bitbucket Server или Data Center — personal access token. Оба пути заканчиваются одинаково: вставьте креды в PanDev Metrics, выберите репозитории и убедитесь, что webhook'и pull request'ов приходят. Аудитория: администратор.

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

  • Версия PanDev Metrics ≥ 1.0.250 (Cloud — всегда)
  • Доступ администратора к воркспейсу PanDev Metrics
  • Пользователь Bitbucket с правами Admin на нужных воркспейсах / проектах (используйте сервисный аккаунт)
  • Для on-prem PanDev Metrics: исходящий 443 к bitbucket.org или к вашему Bitbucket Server / Data Center
  • Чтобы Bitbucket достучался до on-prem PanDev Metrics: хост PanDev Metrics должен быть доступен из Bitbucket по публичному webhook URL

:::tip Используйте сервисный аккаунт Создайте отдельного пользователя Bitbucket под PanDev Metrics (например, pandev-metrics-bot). Добавьте его с правами Admin в нужные воркспейсы. Автоматические комментарии будут отделены от человеческих. :::

Шаг 1 — Создайте креды в Bitbucket​

Тип кред зависит от вашей редакции Bitbucket.

Bitbucket Cloud — создайте app password​

  1. Войдите в Bitbucket Cloud под сервисным аккаунтом.
  2. Откройте Personal Settings → App passwords.
  3. Нажмите Create app password.
  4. Настройте права:
PermissionУровень
RepositoriesRead, Write
Pull requestsRead, Write
WebhooksRead and write
  1. Нажмите Create и сохраните app password — Bitbucket Cloud показывает его только один раз.

Ещё нужен username Bitbucket (виден в правом верхнем углу любой страницы Bitbucket).

Bitbucket Server / Data Center — создайте personal access token​

  1. Войдите в Bitbucket Server / Data Center под сервисным аккаунтом.
  2. Откройте Manage Account → Personal access tokens.
  3. Нажмите Create a token.
  4. Настройте права:
PermissionУровень
RepositoryRead, Write
Pull RequestRead, Write
  1. Нажмите Create и сохраните токен — повторно он не показывается.

Шаг 2 — Откройте экран интеграции Bitbucket в PanDev Metrics​

Войдите в PanDev Metrics как администратор воркспейса и откройте Настройки → Интеграции → Bitbucket.

Выберите ту редакцию, которую вы настроили: Bitbucket Cloud или Bitbucket Server / Data Center.

Шаг 3 — Введите креды и хост​

Поля зависят от редакции.

Для Bitbucket Cloud:

ПолеЗначение
UsernameВаш username Bitbucket Cloud
App passwordЗначение из Шага 1

Для Bitbucket Server / Data Center:

ПолеЗначение
Server URLhttps://bitbucket.acme.example
Personal access tokenЗначение из Шага 1

Нажмите Проверить подключение. PanDev Metrics вызовет API Bitbucket и покажет аутентифицированного пользователя и число доступных репозиториев.

После успешной проверки нажмите Активировать.

Шаг 4 — Выберите репозитории для мониторинга​

PanDev Metrics покажет список воркспейсов (Cloud) или проектов (Server / Data Center), доступных кредам. Выберите репозитории и сохраните.

PanDev Metrics запустит одноразовый backfill за последние 30 дней по коммитам и pull request'ам.

Шаг 5 — Проверьте регистрацию webhook'ов​

PanDev Metrics регистрирует webhook'и в каждом репозитории автоматически. На стороне Bitbucket откройте любой выбранный репозиторий и перейдите в:

  • Repository settings → Webhooks (Cloud)
  • Repository settings → Webhooks (Server / Data Center)

Должна быть запись, указывающая на ingest-URL PanDev Metrics. Для справки — PanDev Metrics обрабатывает следующие endpoints (URL'ы заполняются автоматически при активации):

СобытиеEndpoint PanDev Metrics (информационно)
Жизненный цикл репозитория/v1/bitbucket/webhook/repository
События pull request/v1/bitbucket/webhook/merge-request

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

Проверка​

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

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

Затем откройте дашборд с DORA-метриками — в течение ~15 минут плитки lead time и PR cycle time покажут данные из Bitbucket.

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

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

Для Cloud — неверный app password или ошибка в username (нужен именно username аккаунта, а не display name и не email). Для Server / Data Center — PAT просрочен или отозван. Пересоздайте кред (Шаг 1).

«Проверить подключение» возвращает `404 Not Found` на Server / Data Center

В Server URL лишний путь или хвостовой слэш. Указывайте чистый хост, например https://bitbucket.acme.example, а не https://bitbucket.acme.example/bitbucket/. Если Bitbucket стоит за reverse proxy с context path — обратитесь к своему администратору.

Webhook'и регистрируются, но доставки падают по таймауту

Bitbucket не может достучаться до webhook-URL PanDev Metrics. Для on-prem PanDev Metrics убедитесь, что хост доступен из Bitbucket по публичному URL. С сервера Bitbucket попробуйте: curl -I <pandev-public-url>/v1/bitbucket/webhook/merge-request.

Комментарии в PR не появляются

У app password / токена нет Pull requests: Write, либо в PanDev Metrics отключена опция Публикация комментариев в PR. Откройте Настройки → Интеграции → Bitbucket → Расширенные и проверьте оба пункта. Также проверьте, что нужный репозиторий не исключён.

Синхронизируется только часть репозиториев

У сервисного аккаунта нет доступа к недостающим репозиториям. Добавьте пользователя в нужные воркспейсы (Cloud) или выдайте права на уровне проекта (Server / Data Center) и нажмите Проверить подключение ещё раз.

Что собирается​

PanDev Metrics получает из каждого выбранного репозитория:

  • Коммиты (SHA, автор, время, сообщение, статистика файлов)
  • Ветки и теги
  • Pull request'ы (открытые / смерженные / declined) и их ревью, комментарии и approvals
  • Статусы pipeline / CI, прикреплённых к PR (если есть)

Исходный код не сохраняется. Подробнее — в Как работает плагин.

FAQ​

Какие редакции Bitbucket поддерживаются?​

Bitbucket Cloud, Bitbucket Server и Bitbucket Data Center — все поддерживаются. Процесс настройки одинаков, отличается только тип кред: app password для Cloud, PAT для Server / Data Center.

Какой минимальный набор прав?​

Для Cloud: Repositories: Read+Write и Pull requests: Read+Write в app password. Для Server / Data Center: Repository: Read+Write и Pull Request: Read+Write в PAT. Write-уровень используется для публикации DORA-комментариев — если нужен read-only, отключите комментирование в PanDev Metrics.

Можно ли использовать Bitbucket OAuth вместо app password?​

Пока нет. OAuth-app flow для Bitbucket Cloud не реализован. PanDev Metrics использует app password для Cloud и personal access token для Server / Data Center.

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

Webhook'и доставляют события pull request и коммитов в реальном времени — обычно за секунды. Дополнительно раз в 15 минут PanDev Metrics запускает reconciliation-опрос, чтобы подобрать пропущенные доставки.

Сколько занимает первичный backfill?​

Backfill последних 30 дней. Для 50 репозиториев — обычно 5-15 минут. Большие воркспейсы — до часа. После backfill синхронизация идёт в реальном времени через webhook'и.

Можно ли ограничить интеграцию конкретными репозиториями?​

Да. После активации в любой момент снимите выбор с лишних репозиториев на экране интеграции. PanDev Metrics удалит регистрации webhook'ов с них в течение минут.

В чём разница между Bitbucket Server и Data Center?​

Server — однонодная self-hosted редакция (новые установки Atlassian её больше не предлагает). Data Center — кластерная self-hosted редакция. С точки зрения PanDev Metrics API идентичен — укажите URL хоста и PAT.

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

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