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

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

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

Кратко. Гайд подключает GitLab к PanDev Metrics примерно за 10 минут. Вы создадите personal или group access token со scope'ами api и write_repository, вставите его в PanDev Metrics, укажете правильный URL GitLab и проверите, что события merge request и push попадают в дашборды. Работает одинаково с GitLab.com и GitLab Self-Managed. Аудитория: администратор.

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

  • Версия PanDev Metrics ≥ 1.0.250 (Cloud — всегда)
  • Доступ администратора к воркспейсу PanDev Metrics
  • Пользователь GitLab (желательно сервисный аккаунт) с ролью Maintainer или Owner в нужных группах / проектах
  • Для on-prem PanDev Metrics: исходящий 443 к gitlab.com или к вашему self-managed GitLab
  • Чтобы GitLab достучался до on-prem PanDev Metrics: хост PanDev Metrics должен быть доступен из GitLab по публичному webhook URL

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

Шаг 1 — Создайте access token в GitLab​

Войдите под сервисным аккаунтом и откройте User Settings → Access Tokens (или Group / Project Access Tokens, если хотите ограничить токен одной группой или проектом).

Настройте токен:

ПолеЗначение
Namepandev-metrics
Expiration90 дней (или без срока для Self-Managed)
Scopesapi, write_repository

Нажмите Create personal access token и сразу скопируйте значение — GitLab показывает его только один раз.

:::warning Минимальные scope'ы PanDev Metrics требует api и write_repository. Scope api читает коммиты, merge request'ы и ревью. Scope write_repository нужен для публикации DORA-комментариев в merge request'ах. Если комментировать MR не нужно, можно убрать write_repository и отключить опцию Публикация комментариев в MR в PanDev Metrics — но на экране интеграции появится предупреждение, что часть фич выключена. :::

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

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

Шаг 3 — Введите URL GitLab и токен​

Заполните форму:

ПолеДля GitLab.comДля Self-Managed
GitLab URLhttps://gitlab.comhttps://gitlab.acme.example
Access tokenТокен из Шага 1Токен из Шага 1

Нажмите Проверить подключение. PanDev Metrics вызовет /api/v4/user на вашем GitLab и покажет имя аутентифицированного пользователя и число доступных проектов.

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

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

После активации PanDev Metrics покажет список групп и проектов, доступных сервисному аккаунту. Выберите нужные и сохраните. PanDev Metrics запустит одноразовый backfill за последние 30 дней по коммитам и merge request'ам.

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

PanDev Metrics регистрирует webhook'и в каждом проекте автоматически. Откройте любой выбранный проект и перейдите в Settings → Webhooks. Должна быть запись, указывающая на ingest-URL PanDev Metrics.

Для справки — PanDev Metrics обрабатывает следующие endpoints (вручную их не настраивают, GitLab пушит на URL, прописанный при активации):

СобытиеEndpoint PanDev Metrics (информационно)
Жизненный цикл репозитория / проекта/v1/gitlab/webhook/repository
События merge request/v1/gitlab/webhook/merge-request
События push/v1/gitlab/webhook/push
Агрегированный ingest v2/v2/gitlab/webhook

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

Проверка​

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

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

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

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

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

Токен невалиден, отозван или у него нет scope'а api. Сгенерируйте новый с scope'ами api и write_repository (Шаг 1) и вставьте его.

«Проверить подключение» возвращает «Could not resolve host»

PanDev Metrics не может достучаться до Self-Managed GitLab. Для on-prem PanDev Metrics проверьте egress: docker exec pandev-metrics-app curl -v https://gitlab.acme.example. Откройте фаервол или задайте HTTPS_PROXY на контейнере.

Webhook'и дают 500 со стороны GitLab

GitLab не достучался до webhook-URL PanDev Metrics. Для on-prem развёртываний хост PanDev Metrics должен быть доступен из GitLab по публичному URL (раздел Settings → System → Public URL). Проверьте с машины, у которой такой же сетевой контекст, как у GitLab: curl -I <public-url>/v1/gitlab/webhook/merge-request.

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

Либо у токена нет write_repository, либо отключена опция Публикация комментариев в MR. Откройте Настройки → Интеграции → GitLab → Расширенные и проверьте оба пункта. PanDev Metrics никогда не пишет в MR проектов, исключённых из мониторинга.

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

У сервисного аккаунта нет хотя бы роли Reporter в недостающих проектах. Добавьте его на уровень группы, чтобы дочерние проекты унаследовали доступ, и нажмите Проверить подключение ещё раз.

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

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

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

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

FAQ​

Какой абсолютный минимум scope'ов я могу выдать токену?​

Одного api достаточно для read-only аналитики (коммиты, MR, ревью). Добавьте write_repository, если PanDev Metrics должен публиковать DORA-комментарии в MR. Если write_repository нет, но комментирование включено — PanDev Metrics покажет предупреждение.

Работает ли PanDev Metrics с GitLab Self-Managed?​

Да. Версионного cutoff нет — подходит любой GitLab Self-Managed, отдающий REST API v4. Просто укажите ваш URL в поле GitLab URL.

Personal access token или group / project token?​

Для широкой аналитики — personal access token на сервисном аккаунте, который добавлен в нужные группы. Для одной группы — group access token, для одного проекта — project access token. PanDev Metrics не различает их между собой.

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

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

Можно ли ротировать токен без переустановки?​

Да. Сгенерируйте новый токен в GitLab, затем откройте Настройки → Интеграции → GitLab → Расширенные → Обновить токен в PanDev Metrics. Webhook'и остаются зарегистрированными, backfill не пересчитывается.

Учитываются ли GitLab CI pipelines?​

Да. Статусы pipeline, прикреплённых к merge request'ам, читаются через стандартный GitLab API. PanDev Metrics использует их для метрик deployment frequency и change failure rate.

Что будет, если сервисный аккаунт потеряет доступ к проекту?​

PanDev Metrics пометит проект как Недоступен на экране интеграции и перестанет с ним работать. Верните доступ в GitLab и нажмите Проверить подключение — синхронизация возобновится через минуты.

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

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