PanDev + GitLab: полная настройка за 15 минут

Подключение GitLab к PanDev Metrics занимает около 15 минут. После этого каждый коммит, merge request и событие pipeline автоматически поступают в вашу инженерную панель.

Это руководство охватывает как GitLab SaaS (gitlab.com), так и self-managed инстансы. Никаких плагинов, никаких сложных OAuth-потоков — только webhooks и personal access token.

Что вы получите

После настройки интеграции PanDev Metrics будет отслеживать:

• Коммиты — кто коммитил, когда, что изменилось и сколько строк
• Merge Requests — время до открытия, длительность ревью, cycle time мержа
• Ревью MR — комментарии, аппрувы, запросы на изменения по каждому ревьюеру
• События репозитория — создание веток, push тегов, запуски pipeline

Всё это наполняет ваши DORA-метрики, дашборды cycle time и профили отдельных контрибьюторов.

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

Перед началом убедитесь, что у вас есть:

Требование	Подробности
Аккаунт GitLab	Роль Owner или Maintainer в проектах, которые вы хотите отслеживать
Аккаунт PanDev Metrics	Роль Admin или Manager
Сетевой доступ	Ваш инстанс GitLab должен иметь доступ к webhook-эндпоинту PanDev (или к вашему on-premise инстансу PanDev)

Шаг 1: Сгенерируйте Personal Access Token в GitLab

PanDev нужен доступ на чтение к вашим репозиториям и merge requests. Personal Access Token (PAT) — самый простой способ это обеспечить.

1. В GitLab перейдите в User Settings → Access Tokens
2. Нажмите Add new token
3. Настройте токен:

Token name: pandev-metrics-integration
Expiration date: (установите на 1 год или согласно вашей политике безопасности)
Scopes: ✅ read_api
         ✅ read_repository

4. Нажмите Create personal access token
5. Скопируйте токен сразу — вы не увидите его снова

Group Access Tokens

Если вы подключаете несколько проектов в рамках одной группы, рассмотрите использование Group Access Token. Перейдите в Group → Settings → Access Tokens и следуйте тем же шагам. Это позволяет не привязывать интеграцию к конкретному пользовательскому аккаунту.

Шаг 2: Добавьте токен в PanDev Metrics

1. Войдите в PanDev Metrics
2. Перейдите в Settings → Integrations → GitLab
3. Нажмите Add GitLab Connection
4. Заполните данные подключения:

GitLab URL: https://gitlab.com  (или URL вашего self-managed инстанса)
Access Token: glpat-xxxxxxxxxxxxxxxxxxxx

5. Нажмите Test Connection

Вы должны увидеть зелёную галочку и список доступных групп и проектов. Если тест не прошёл, проверьте scopes токена и сетевое подключение.

Шаг 3: Выберите проекты для отслеживания

После успешного подключения PanDev покажет все проекты, к которым есть доступ у вашего токена.

1. Используйте поиск или просмотрите дерево групп
2. Отметьте чекбоксы рядом с проектами, которые хотите отслеживать
3. Нажмите Save Selection

Крупные организации

Если у вас 50+ проектов, вы можете выбрать целые группы. PanDev автоматически подхватит новые проекты, добавленные в эту группу позднее.

Шаг 4: Настройте Webhooks

Webhooks делают интеграцию работающей в реальном времени. Без них PanDev пришлось бы опрашивать API GitLab — медленнее и с ограничением по rate limit.

PanDev может создавать webhooks автоматически, но вот как это сделать вручную, если ваша политика безопасности этого требует.

Автоматическая настройка (рекомендуется)

На странице интеграции PanDev нажмите Setup Webhooks Automatically. PanDev создаст webhook на каждом выбранном проекте с правильным URL и событиями.

Ручная настройка

Если вы предпочитаете создавать webhooks самостоятельно:

1. В GitLab перейдите в Project → Settings → Webhooks
2. Нажмите Add new webhook
3. Настройте:

URL: https://hooks.pandev-metrics.com/api/v1/gitlab/webhook
Secret token: (скопируйте из PanDev Settings → Integrations → GitLab → Webhook Secret)

Trigger events:
  ✅ Push events
  ✅ Merge request events
  ✅ Comments
  ✅ Pipeline events (опционально — для отслеживания deployment в DORA)
  
SSL verification: ✅ Enable SSL verification

4. Нажмите Add webhook
5. Протестируйте, нажав на выпадающий список Test → Push events

Вы должны увидеть ответ 200 OK. Если получаете таймаут, проверьте правила файрвола.

Group-Level Webhooks (GitLab Premium)

Если у вас GitLab Premium или Ultimate, вы можете настроить один webhook на уровне группы:

1. Перейдите в Group → Settings → Webhooks
2. Используйте тот же URL и secret, что и выше
3. Это покроет все текущие и будущие проекты в группе

Шаг 5: Проверьте поток данных

Подождите минуту, затем проверьте PanDev Metrics:

1. Перейдите в Dashboard → Activity Feed
2. Вы должны увидеть недавние коммиты и merge requests
3. Откройте любой проект в PanDev — вкладки Commits и Merge Requests должны показывать данные

Если данные не поступают:

Симптом	Решение
Нет данных вообще	Проверьте логи доставки webhook в GitLab (Project → Settings → Webhooks → Edit → Recent Deliveries)
Коммиты есть, но нет MR	Убедитесь, что Merge request events включён в webhook
Ошибки 401 в логах webhook	Перегенерируйте webhook secret в PanDev и обновите его в GitLab
Ошибки таймаута	Проверьте, разрешён ли исходящий трафик к hooks.pandev-metrics.com на порту 443

Шаг 6: Сопоставьте пользователей GitLab с профилями PanDev

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

1. Перейдите в Settings → Team Management
2. PanDev покажет список обнаруженных имён пользователей GitLab
3. Сопоставьте каждое имя с правильным профилем участника команды
4. Если разработчик использует несколько email-адресов для коммитов, добавьте все алиасы в его профиль

Этот шаг важен для:

• Точных индивидуальных метрик продуктивности
• Корректной атрибуции cycle time
• Кроссплатформенного разрешения идентичности (если один человек использует GitLab + Jira)

Шаг 7: Настройте параметры метрик (опционально)

Тонкая настройка того, что PanDev отслеживает:

Рабочие часы

Settings → Organization → Working Hours

По умолчанию: Пн-Пт, 09:00-18:00
Часовой пояс: автоопределение для каждого пользователя или общий для организации

Расчёт cycle time по умолчанию использует рабочие часы. Merge request, открытый в пятницу в 17:00 и смерженный в понедельник в 10:00, считается за 1 рабочий час, а не за 65 календарных часов.

Исключённые пути

Отфильтруйте шум от автогенерируемых файлов:

Settings → Projects → [Ваш проект] → Excluded Paths

Примеры:
  - package-lock.json
  - yarn.lock
  - *.generated.ts
  - vendor/**
  - dist/**

Фильтры веток

Отслеживайте только значимые ветки:

Settings → Projects → [Ваш проект] → Branch Filters

Include: main, master, develop, release/*, feature/*
Exclude: dependabot/*, renovate/*

Как выглядит ваш дашборд после настройки

В течение 24 часов после настройки (или быстрее, если ваша команда активна) вы увидите:

• Разбивка Cycle Time — от первого коммита до мержа, с разделением на время кодирования, ревью и ожидания
• Пропускная способность MR — сколько merge requests отправляется в день/неделю
• Нагрузка на ревью — кто ревьюит больше всех и как быстро
• Паттерны коммитов — когда ваша команда наиболее активна
• Метрики DORA — частота деплоев, lead time, MTTR и change failure rate (требуются pipeline webhooks)

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

Ошибка "Token expired" через несколько месяцев

У PAT в GitLab есть срок действия. Установите напоминание в календаре, чтобы ротировать токен до его истечения. Обновите его в PanDev → Settings → Integrations → GitLab → Edit Connection.

Self-managed GitLab за VPN

Два варианта:

1. Добавьте IP-диапазон PanDev в allow-list — свяжитесь с support@pandev-metrics.com для получения актуального списка IP
2. Разверните PanDev on-premise — запустите PanDev внутри вашей сети через Docker или Kubernetes (смотрите наше руководство по on-premise развёртыванию)

Сбои доставки webhook после обновления GitLab

После крупных обновлений GitLab подпись webhook может измениться. Перетестируйте ваши webhooks и перегенерируйте secret при необходимости.

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

Ваша интеграция с GitLab работает. Вот что делать дальше:

• Добавьте IDE-плагины — установите плагин для VS Code или JetBrains для отслеживания времени кодирования
• Подключите Jira или ClickUp — свяжите активность в коде с задачами и спринтами
• Настройте командные дашборды — создайте представления для каждого тимлида
• Включите AI-ассистент — задавайте вопросы вроде «Какой был средний cycle time в прошлом спринте?»

---

Готовы подключить GitLab? Начните с PanDev Metrics — настройка занимает 15 минут, а первые инсайты появляются в течение нескольких часов.