PanDev + GitHub: интеграция через GitHub App

PanDev Metrics интегрируется с GitHub через специализированное GitHub App — никаких personal access tokens для управления, никакой ручной настройки webhook и тонкие разрешения из коробки.

Это руководство проведёт вас через весь процесс: установка приложения, выдача разрешений и проверка того, что данные о коммитах и pull requests поступают в ваши дашборды.

GitHub App vs. Personal Access Token

Прежде чем начать, разберёмся, почему PanDev использует GitHub App вместо PAT:

Характеристика	GitHub App	Personal Access Token
Привязка к человеку	Нет — устанавливается на уровне организации	Да — если человек уйдёт, интеграция сломается
Разрешения	Тонкие, по каждому репозиторию	Широкие scopes
Rate limits	Выше (5,000+ запросов/час)	Ниже (5,000 запросов/час, общие для всех инструментов)
Управление webhook	Автоматическое	Ручное
OAuth для пользователей	Встроенный	Требуется отдельная настройка

Подход через GitHub App — рекомендуемый GitHub паттерн интеграции для сторонних инструментов.

Предварительные требования

Требование	Подробности
Аккаунт GitHub	Роль Organization Owner для установки приложения или личный аккаунт для персональных репозиториев
Аккаунт PanDev Metrics	Роль Admin или Manager
Репозитории	Хотя бы один репозиторий, который вы хотите отслеживать

Шаг 1: Начните подключение в PanDev

1. Войдите в PanDev Metrics
2. Перейдите в Settings → Integrations → GitHub
3. Нажмите Connect GitHub

PanDev перенаправит вас на страницу установки приложения GitHub.

Шаг 2: Установите PanDev GitHub App

На странице установки GitHub:

1. Выберите организацию (или ваш личный аккаунт), куда хотите установить приложение
2. Выберите доступ к репозиториям:

◉ All repositories
   PanDev будет автоматически отслеживать новые репозитории по мере их создания.
   
○ Only select repositories
   Выберите конкретные репозитории из списка ниже.

Для большинства команд "Only select repositories" — более безопасный начальный вариант. Добавить ещё можно в любой момент.

3. Ознакомьтесь с разрешениями, которые запрашивает приложение:

Repository permissions:
  Contents:        Read-only  (для чтения коммитов и файлов)
  Metadata:        Read-only  (базовая информация о репозитории)
  Pull requests:   Read-only  (для отслеживания PR, ревью, комментариев)
  Checks:          Read-only  (опционально — для метрик CI/CD)
  
Organization permissions:
  Members:         Read-only  (для сопоставления пользователей с профилями)

Events:
  ✅ Push
  ✅ Pull request
  ✅ Pull request review
  ✅ Pull request review comment
  ✅ Check run (опционально)

4. Нажмите Install & Authorize

GitHub перенаправит вас обратно в PanDev.

Шаг 3: Завершите авторизацию OAuth

После установки приложения PanDev попросит авторизоваться через OAuth. Это отдельный шаг от установки приложения — он связывает вашу личную идентичность GitHub с профилем PanDev.

1. Нажмите Authorize PanDev Metrics
2. GitHub покажет экран согласия OAuth
3. Нажмите Authorize

Вы будете перенаправлены обратно в PanDev и увидите сообщение об успехе:

✅ GitHub connected successfully
   Organization: your-org
   Repositories: 12 selected

Шаг 4: Проверьте обнаружение репозиториев

После подключения PanDev импортирует метаданные из выбранных репозиториев:

1. Перейдите в Settings → Integrations → GitHub
2. Вы увидите вашу организацию со списком подключённых репозиториев
3. Каждый репозиторий показывает статус синхронизации:

Repository              Status         Last Sync
───────────────────────────────────────────────────
your-org/frontend       ✅ Active      Just now
your-org/backend-api    ✅ Active      Just now
your-org/infra          ✅ Active      Just now
your-org/docs           ⏸ Paused       —

Если репозиторий показывает статус "Paused", значит PanDev его обнаружил, но вы не включили отслеживание. Нажмите на переключатель, чтобы активировать.

Шаг 5: Импорт исторических данных

PanDev автоматически импортирует исторические данные за последние 90 дней при первом подключении репозитория. Это включает:

• Все коммиты в default-ветке и ветках смерженных PR
• Все pull requests (открытые, закрытые, смерженные)
• Все ревью и комментарии к PR
• Все check runs и статусы pipeline

Импорт выполняется в фоне. Для типичного репозитория с несколькими тысячами коммитов это занимает 2–5 минут. Крупные монорепозитории (100K+ коммитов) могут импортироваться до 30 минут.

Отслеживайте прогресс в Settings → Integrations → GitHub → Import Status.

Шаг 6: Сопоставьте пользователей GitHub с участниками команды

Для точных метрик PanDev нужно связать идентичности GitHub с профилями участников команды.

1. Перейдите в Settings → Team Management
2. PanDev покажет список обнаруженных имён пользователей GitHub из ваших репозиториев
3. Для каждого пользователя:
   • Автоматическое сопоставление — PanDev попытается сопоставить по email
   • Ручное сопоставление — выберите нужного участника из выпадающего списка
   • Игнорировать — для ботов, сервисных аккаунтов или внешних контрибьюторов, которых не нужно отслеживать

Работа с несколькими идентичностями

Разработчики часто коммитят с разными email-адресами или именами:

Один и тот же человек, разные идентичности:
  - GitHub user: @jsmith
  - Commit email: john.smith@company.com
  - Commit email: john@personal.email
  - Git author: "John Smith"
  - Git author: "jsmith"

В PanDev перейдите в профиль участника команды и добавьте все алиасы в раздел Identity Aliases. PanDev объединит активность со всех идентичностей в единый профиль.

Шаг 7: Настройте параметры отслеживания

Исключение шумных файлов

Предотвратите искажение метрик количества строк автогенерируемыми файлами:

# Settings → Projects → [Repo] → Excluded Paths
excluded_paths:
  - "package-lock.json"
  - "yarn.lock"
  - "Gemfile.lock"
  - "*.generated.*"
  - "vendor/**"
  - "node_modules/**"
  - "dist/**"
  - "__snapshots__/**"

Стратегия веток

Расскажите PanDev, как ваша команда использует ветки:

Settings → Projects → [Repo] → Branch Configuration

Default branch: main
Production branches: main, release/*
Feature branch pattern: feature/*, fix/*, chore/*
Ignored branches: dependabot/*, renovate/*, gh-pages

Это влияет на расчёт cycle time — PanDev измеряет время от первого коммита в feature-ветке до мержа в production-ветку.

Рабочие часы

Settings → Organization → Working Hours

Расписание: Понедельник–Пятница
Часы: 09:00–18:00
Часовой пояс: America/New_York (или для каждого пользователя)
Исключить праздники: ✅ (загрузите календарь праздников компании)

Шаг 8: Исследуйте ваш дашборд

С поступающими данными дашборд наполняется за считанные минуты. Вот на что стоит обратить внимание в первую очередь:

Метрики Pull Request

Метрика	Что показывает
PR Cycle Time	Общее время от открытия PR до мержа
Time to First Review	Как долго PR ждёт первого ревью
Review Turnaround	Время между запросом ревью и его предоставлением
PR Size	Количество изменённых строк на PR (меньше — обычно лучше)
PR Throughput	Количество смерженных PR в день/неделю/спринт

Метрики коммитов

Метрика	Что показывает
Commit Frequency	Коммиты на разработчика в день
Active Contributors	Уникальные контрибьюторы в неделю
Code Churn	Строки, добавленные и затем изменённые в рамках одного спринта

Метрики DORA

Если вы включили события check run:

Метрика DORA	Источник
Deployment Frequency	Смерженные PR в production-ветки
Lead Time for Changes	Первый коммит → мерж в production
Mean Time to Recovery	Время между сбоем и деплоем исправления
Change Failure Rate	Соотношение неудачных и общих деплоев

Управление GitHub App

Добавление новых репозиториев

1. Перейдите в GitHub → Settings → Applications → PanDev Metrics → Configure
2. В разделе "Repository access" добавьте новые репозитории
3. PanDev автоматически обнаружит изменение и начнёт синхронизацию

Удаление репозиториев

Тот же путь — уберите галочки с репозиториев, которые больше не хотите отслеживать. Исторические данные сохраняются в PanDev 90 дней после отключения.

Удаление приложения

Для полного удаления интеграции:

1. На стороне GitHub: Settings → Applications → PanDev Metrics → Uninstall
2. На стороне PanDev: Settings → Integrations → GitHub → Disconnect

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

Нет данных после установки

1. Проверьте доставку webhooks: GitHub → Repo → Settings → Webhooks → Recent Deliveries
2. Убедитесь в корректности разрешений приложения: GitHub → Settings → Applications → PanDev Metrics → Permissions
3. Убедитесь, что репозиторий включён в PanDev (не на паузе)

Ошибка "Insufficient permissions"

GitHub App должно быть установлено Organization Owner. Если вы рядовой участник, попросите владельца установить приложение, а затем авторизуйтесь своим аккаунтом через OAuth.

Rate limiting при импорте исторических данных

Для очень крупных организаций (1,000+ репозиториев) PanDev распределяет импорт, чтобы не превышать rate limits GitHub. Импорт может занять несколько часов. Прогресс отображается на странице статуса импорта.

GitHub Enterprise Server (self-hosted)

PanDev поддерживает GitHub Enterprise Server. При настройке выберите "GitHub Enterprise" и введите URL вашего инстанса:

GitHub Enterprise URL: https://github.yourcompany.com

Процесс установки GitHub App работает так же. Убедитесь, что ваш GitHub Enterprise инстанс может достигать webhook-эндпоинта PanDev, или разверните PanDev on-premise.

Следующие шаги

Ваша интеграция с GitHub работает. Рассмотрите следующие действия:

• Подключите трекер задач — свяжите Jira или ClickUp для корреляции активности в коде с задачами
• Установите IDE-плагины — добавьте плагины VS Code или JetBrains для данных о времени кодирования
• Поделитесь дашбордами — пригласите тимлидов в PanDev и создайте представления по командам
• Настройте алерты — получайте уведомления, когда cycle time превышает пороговое значение вашей команды

---

Подключите GitHub за 5 минут. Начните отслеживать инженерные метрики с PanDev Metrics — никаких токенов для ротации, никакой ручной настройки webhooks.