Интеграция GitHub с PanDev Metrics
Кратко. Гайд подключает GitHub к PanDev Metrics примерно за 10 минут. Вы установите GitHub App в свою организацию (рекомендуемый путь) или сгенерируете OAuth-токен, вставите его в PanDev Metrics и убедитесь, что коммиты, pull request'ы и ревью начали попадать в дашборды. Аудитория: администратор.
Что понадобится
- Версия PanDev Metrics ≥ 1.0.250 (для Cloud это выполняется всегда)
- Доступ администратора к воркспейсу PanDev Metrics
- Роль Owner или Admin в GitHub-организации (нужна для установки App)
- Для on-prem PanDev Metrics: инстанс должен иметь доступ к
api.github.com(Cloud) или к хосту GitHub Enterprise Server по 443 порту - Чтобы GitHub мог достучаться до on-prem PanDev Metrics: хост PanDev Metrics должен быть доступен из GitHub по публичному webhook URL
:::tip Рекомендуемый путь Мы рекомендуем GitHub App — он раздаёт права по конкретным репозиториям, регистрирует webhook'и автоматически и сам ротирует креды. :::
Шаг 1 — Выберите GitHub App или OAuth
PanDev Metrics поддерживает два режима подключения GitHub. Определитесь до начала.
| Режим | Когда использовать | Модель прав |
|---|---|---|
| GitHub App (рекомендуется) | Подключение на уровне организации, точечный выбор репозиториев | Repository: Read, Pull Requests: Read/Write |
| OAuth / Personal Access Token | Один репозиторий или быстрый тест через сервисный аккаунт | Те же scope'ы через fine-grained PAT |
Дальше описан путь через GitHub App. Для OAuth откройте тот же экран и вставьте fine-grained PAT с правами Contents: Read и Pull requests: Read and write вместо установки App.
Шаг 2 — Откройте экран интеграции GitHub в PanDev Metrics
Войдите в PanDev Metrics как администратор воркспейса и откройте Настройки → Интеграции → GitHub.
Если карточки GitHub не видно — в вашей редакции интеграция не активирована. Свяжитесь со своим администратором или запросите доступ.
Шаг 3 — Установите PanDev Metrics GitHub App
Нажмите Установить GitHub App. PanDev Metrics перенаправит вас на GitHub. На странице GitHub:
- Выберите организацию, куда установить App.
- Выберите All repositories или Only select repositories (это можно поменять позже в GitHub).
- Проверьте запрашиваемые права:
| Permission | Уровень | Зачем |
|---|---|---|
| Repository contents | Read-only | Чтение коммитов, веток и файлов для анализа |
| Pull requests | Read and write | Чтение метаданных PR; публикация комментариев с метриками |
| Metadata | Read-only | Перечисление репозиториев — обязательно для любого GitHub App |
- Нажмите Install. GitHub вернёт вас в PanDev Metrics с заполненным installation ID.
:::note Для on-prem
Администраторы on-prem задают три переменные окружения на контейнере PanDev Metrics: GITHUB_APP_NAME, GITHUB_APP_ID и GITHUB_PRIVATE_KEY_BASE_64 (private key App'а, закодированный в base64). Полный список переменных см. в Сети и порты on-prem.
:::
Шаг 4 — Подтвердите подключение в PanDev Metrics
Вернувшись на экран интеграции GitHub, вы увидите свою организацию в списке Подключённые установки. Нажмите Проверить подключение — PanDev Metrics вызовет GitHub API и подтвердит, что App имеет доступ к нужным репозиториям.
После успешной проверки нажмите Активировать. PanDev Metrics запустит одноразовый backfill за последние 30 дней по коммитам и pull request'ам.
Шаг 5 — Проверьте доставку webhook'ов
PanDev Metrics регистрирует webhook'и автоматически при установке App. Чтобы убедиться, что они приходят, откройте любой подключённый репозиторий и перейдите в Settings → Webhooks на GitHub.
Доставки идут через установленный App; обрабатываются следующие endpoints PanDev Metrics:
| Событие | Endpoint PanDev Metrics (информационно) |
|---|---|
repository (создан / архивирован / переименован) | /v1/github/webhook/repository |
pull_request (открыт / изменён / закрыт / смержен) | /v1/github/webhook/pull-request |
installation и другие App-level события | /v1/github/app/webhook |
URL'ы прописываются автоматически при установке App. Доставки должны возвращать HTTP 200 в течение секунд.
Проверка
Откройте Настройки → Интеграции → GitHub в PanDev Metrics. Вы увидите:
- Зелёный бейдж Подключено рядом с каждой установкой
- Количество найденных репозиториев
- Время последней синхронизации (не старше 30 минут после завершения backfill)
Затем откройте любой дашборд с DORA-метриками — в течение ~15 минут после активации плитки deployment frequency и lead time покажут данные из GitHub.
Решение проблем
App установлен, но PanDev Metrics показывает «0 репозиториев»
App установлен на уровне организации с Only select repositories и пустым списком. Откройте GitHub Settings → Applications → Installed GitHub Apps → PanDev Metrics → Configure и либо выберите репозитории, либо переключитесь на All repositories. PanDev Metrics пере-синхронизируется в течение 5 минут.
Webhook'и возвращают 403 Forbidden или 401
Обычно это значит, что PanDev Metrics ротировал installation-токен после ручного изменения прав. Переустановите App: GitHub Settings → Applications → PanDev Metrics → Configure → Uninstall, затем повторите Шаг 3.
On-prem PanDev Metrics не может достучаться до api.github.com
Проверьте egress из контейнера PanDev Metrics: docker exec pandev-metrics-app curl -v https://api.github.com/zen. Если запрос падает — фаервол блокирует исходящий 443. Откройте маршрут или задайте HTTPS_PROXY в окружении контейнера.
GitHub Enterprise Server отвечает 404 на API-запрос
Для GHES базовый API URL — https://<ваш-ghes-хост>/api/v3, а не корень хоста. Укажите это в поле GitHub host на экране интеграции. GitHub App тоже должен быть установлен на GHES, а не на github.com.
Комментарии к PR не появляются, хотя подключение зелёное
Публикация комментариев качества — отдельная настройка. Откройте Настройки → Интеграции → GitHub → Расширенные и включите Публиковать комментарии с метриками в PR. Настройка уважает per-repository переопределения — проверьте, что нужный репозиторий не исключён.
Что собирается
PanDev Metrics получает из каждого подключённого репозитория:
- Коммиты (SHA, автор, время, сообщение, статистика файлов)
- Ветки и теги
- Pull request'ы (открытые / смерженные / закрытые) и их ревью, комментарии и review request'ы
- Статусы CI-проверок, прикреплённых к PR (если есть)
Исходный код не сохраняется. Подробнее о потоке данных и хранении — в статье Как работает плагин.
FAQ
Что выбрать — GitHub App или OAuth?
Выбирайте GitHub App для любого реального подключения, не считая разового теста. App раздаёт права по репозиториям, сам ротирует креды и не зависит от увольнений (он не привязан к личному аккаунту). OAuth-токены годятся для коротких тестов.
Какие минимальные права нужны PanDev Metrics?
Repository: Read и Pull requests: Read and write. Write-уровень используется только для публикации DORA-комментариев в pull request'ах — это можно отключить в Расширенных настройках, если нужен полностью read-only доступ.
Работает ли PanDev Metrics с GitHub Enterprise Server?
Да. Тот же GitHub App ставится на GHES; PanDev Metrics принимает кастомный URL GitHub-хоста на экране интеграции. Для on-prem PanDev Metrics нужен сетевой доступ от хоста PanDev Metrics к вашему GHES по 443 порту.
Как аутентифицируются webhook'и?
PanDev Metrics подписывает каждый webhook-URL зашифрованными query-параметрами company и department. Управлять секретами подписи вручную не нужно — App регистрирует и ротирует их автоматически.
Сколько идёт первичный backfill?
PanDev Metrics при активации подтягивает последние 30 дней коммитов и pull request'ов. Для типичной организации из 50 репозиториев это занимает 5-15 минут. Крупные организации (500+ репозиториев) — до часа. После backfill синхронизация идёт в реальном времени через webhook'и.
Можно ли ограничить интеграцию конкретными репозиториями?
Да. Либо выберите Only select repositories при установке GitHub App, либо в любой момент откройте Settings → Applications → PanDev Metrics → Configure на GitHub. PanDev Metrics учтёт изменение в течение минут.
Видит ли PanDev Metrics исходный код приватных репозиториев?
Нет. PanDev Metrics читает метаданные коммитов (SHA, автор, время, сообщение, статистика файлов) и метаданные pull request'ов. Содержимое файлов и diff'ы не сохраняются.
Можно ли ротировать private key GitHub App?
Да. Сгенерируйте новый ключ в GitHub Settings → Developer settings → GitHub Apps → PanDev Metrics → Private keys, затем обновите GITHUB_PRIVATE_KEY_BASE_64 на контейнере PanDev Metrics и перезапустите его. Cloud-клиенты ключ сами не трогают.
Дальнейшие шаги
- Подключите трекер задач — свяжите коммиты и PR с задачами Jira / Yandex Tracker / Notion
- Установите JetBrains-плагин — показывает метрики прямо в IDE
- Сети и порты on-prem — правила egress для self-hosted развёртываний
Связанные материалы
- How-to: Интеграция GitLab
- How-to: Интеграция Bitbucket
- How-to: Интеграция Azure DevOps