Руководство по интеграции с GitVerse

Руководство по подключению CodeGraph к платформе GitVerse (СберТех) для автоматического анализа кода, поиска уязвимостей и отслеживания технического долга.

Содержание

Обзор

GitVerse – платформа размещения git-репозиториев от СберТех (экосистема Сбера). CodeGraph интегрируется с GitVerse по трём направлениям:

  • CI/CD-конвейер – CodeGraph как шаг в .gitverse/workflows/
  • Вебхуки – автоматическое обновление CPG при коммитах и анализ запросов на слияние
  • Автономный – развёрнут рядом с GitVerse, доступен через REST API / CLI / MCP и через выделенный Web route /dashboard/gitverse

GitVerse использует формат полезной нагрузки, совместимый с GitHub (pull_request, head_commit). CodeGraph нормализует их автоматически.

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

  • Работающий экземпляр CodeGraph (Docker или локальная установка), доступный для раннеров GitVerse
  • Учётная запись GitVerse с доступом к API и правами администратора репозитория (для вебхуков)
  • Docker (для шагов CI-конвейера)
  • Ключ API GigaChat (GIGACHAT_AUTH_KEY)

Docker-образ

Официальный Docker-образ CodeGraph публикуется в GitHub Container Registry через .github/workflows/publish-ghcr.yml, тегируется по версиям (v*) и latest.

docker pull ghcr.io/mkhlsavin/codegraph:latest
docker run --rm ghcr.io/mkhlsavin/codegraph:latest python -m src.cli health

Образ включает GoCPG-парсер и поддерживает 11 языков.

Настройка вебхуков

Конечная точка: POST /api/v1/webhooks/gitverse (возвращает 202 Accepted)

Настройка в GitVerse: Настройки репозитория → Вебхуки → Добавить вебхук: 1. URL: https://<codegraph-host>/api/v1/webhooks/gitverse 2. Тип содержимого: application/json 3. Секретный ключ: произвольная строка для подписи HMAC-SHA256 4. События: Push и Pull Request

Проверка подписи

CodeGraph верифицирует заголовок X-GitVerse-Signature (HMAC-SHA256). При отсутствии проверяет X-Hub-Signature-256 для совместимости с GitHub.

Коды ошибок: - 401 Unauthorized – отсутствует заголовок подписи - 403 Forbidden – невалидная подпись (несовпадение HMAC)

Защита от повторного воспроизведения

Вебхуки включают заголовок X-GitVerse-Timestamp (Unix epoch). CodeGraph проверяет, что временна́я метка не старше 300 секунд (5 минут) для защиты от replay-атак. Устаревшие вебхуки отклоняются с кодом 400 Bad Request.

Поддерживаемые события

Событие Действие
push Инкрементальное обновление CPG
pull_request (opened/synchronize) Запуск анализа кода

Конфигурация

Секция gitverse в config.yaml:

gitverse:
  webhook_secret: ''            # Секретный ключ HMAC-SHA256
  auto_update_on_push: true     # Обновлять CPG при событии push
  api_url: https://gitverse.ru/api/v1

CI-конвейер

Готовый шаблон находится в ci/gitverse/codegraph-review.yaml. Скопируйте его в репозиторий:

mkdir -p .gitverse/workflows
cp ci/gitverse/codegraph-review.yaml .gitverse/workflows/codegraph-review.yaml

Переменные и секреты:

Переменная Тип Описание
CODEGRAPH_URL Переменная Адрес API CodeGraph, например https://codegraph.example.com
CODEGRAPH_API_TOKEN Секрет Токен аутентификации API
GITVERSE_TOKEN Секрет Токен доступа GitVerse для публикации комментариев
PROJECT_LANGUAGE Переменная Язык исходного кода (по умолчанию python)

Этапы (запуск при pull_request: opened, synchronize, reopened):

  1. Сборка CPG – gocpg parse в контейнере ghcr.io/mkhlsavin/codegraph:latest
  2. Сканирование безопасности – межпроцедурный анализ потоков данных по diff
  3. Рецензирование PR – структурный анализ через /api/v1/review/gitverse
  4. Отчёт – сводка результатов в артефактах задания

Ключевой фрагмент конвейера (полная версия в ci/gitverse/codegraph-review.yaml):

jobs:
  cpg-update:
    name: Build CPG
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/mkhlsavin/codegraph:latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Build CPG
        run: |
          gocpg parse --input=. --output=/tmp/cpg.duckdb \
            --lang=${{ vars.PROJECT_LANGUAGE || 'python' }}

  pr-review:
    name: PR Review
    needs: cpg-update
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/mkhlsavin/codegraph:latest
    steps:
      - name: Review PR
        run: |
          curl -sf -X POST "${CODEGRAPH_URL}/api/v1/review/gitverse" \
            -H "Authorization: Bearer ${CODEGRAPH_TOKEN}" \
            -H "X-GitVerse-Token: ${{ secrets.GITVERSE_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"project_id": "${{ github.repository }}", "pr_number": ${{ github.event.pull_request.number }}, "publish_review": true}' \
            -o review-results.json

OAuth-аутентификация

CodeGraph поддерживает OAuth-авторизацию через GitVerse для единого входа (SSO).

Переменные окружения

Переменная Описание Значение по умолчанию
OAUTH_GITVERSE_CLIENT_ID Идентификатор OAuth-приложения –
OAUTH_GITVERSE_CLIENT_SECRET Секрет OAuth-приложения –
OAUTH_GITVERSE_SERVER_URL Базовый URL сервера GitVerse https://gitverse.ru

Конечные точки

OAuth использует параметризованные маршруты, работающие для любого настроенного провайдера:

Конечная точка Описание
GET /api/v1/auth/oauth/{provider} Инициирует OAuth-поток, перенаправляет на провайдера
GET /api/v1/auth/oauth/{provider}/callback Обратный вызов OAuth, обмен кода на JWT-токен

Для GitVerse используйте provider=gitverse: - Авторизация: GET /api/v1/auth/oauth/gitverse - Обратный вызов: GET /api/v1/auth/oauth/gitverse/callback - Discoverability: GET /api/v1/auth/oauth/providers включает gitverse, если провайдер настроен

Построение URL авторизации

OAuth автоматически включается при установке OAUTH_GITVERSE_CLIENT_ID. Провайдер строит URL из базового адреса сервера:

  • Авторизация: {server_url}/oauth/authorize
  • Обмен токенов: {server_url}/oauth/token
  • Данные пользователя: {server_url}/api/v1/user

Поддержка Sber ID

Для организаций, использующих Sber ID в качестве поставщика удостоверений, установите OAUTH_GITVERSE_SERVER_URL на адрес корпоративного экземпляра GitVerse, который проксирует авторизацию через Sber ID:

export OAUTH_GITVERSE_SERVER_URL="https://gitverse.company.ru"

Operator Surfaces

  • Web: /dashboard/gitverse собирает onboarding, project health и audit drill-down в единый GitVerse flow
  • CLI: codegraph gitverse status|bindings|template|review-dry-run
  • MCP: codegraph_gv_review, codegraph_gv_pr_info, codegraph_gv_commit_status, codegraph_gv_summary

REST API

POST /api/v1/review/gitverse – Рецензирование PR

Получает diff запроса на слияние из GitVerse и выполняет структурный анализ кода (зона поражения, дельта сложности, мёртвый код, безопасность).

Заголовки: Authorization: Bearer <token>, X-GitVerse-Token: <gitverse-pat>

Тело запроса:

{
  "project_id": "owner/repo",
  "pr_number": 42,
  "gitverse_url": "https://gitverse.ru/api/v1",
  "publish_review": true,
  "task_description": "Описание задачи (необязательно)",
  "dod_items": ["Критерий готовности 1", "Критерий готовности 2"]
}

Ответ (ReviewResponse):

{
  "recommendation": "REQUEST_CHANGES",
  "score": 72.5,
  "findings": [
    {
      "category": "security",
      "severity": "high",
      "location": {"file": "src/auth.py", "line_start": 45},
      "message": "Непроверенный пользовательский ввод передаётся в SQL-запрос",
      "suggested_fix": "Используйте параметризованный запрос"
    }
  ],
  "dod_validation": [
    {
      "description": "Критерий готовности 1",
      "satisfied": true,
      "evidence": "Все 42 теста проходят"
    }
  ],
  "summary": "Обнаружены проблемы безопасности и архитектуры",
  "processing_time_ms": 3200.0,
  "request_id": "req_abc123",
  "metadata": {}
}

dod_validation – необязательное поле. Возвращается только при передаче dod_items в запросе, иначе null.

Значения recommendation: APPROVE, REQUEST_CHANGES, COMMENT, BLOCK.

POST /api/v1/webhooks/gitverse – Приём вебхуков

Принимает события push и pull_request в формате, совместимом с GitHub. Возвращает 202 Accepted – обработка выполняется асинхронно. Подробнее см. раздел Настройка вебхуков.

POST /api/v1/review/summary – Генерация описания MR

Принимает diff_content (обязательно), title и description (необязательно). Возвращает структурированное описание: краткое содержание изменений, список изменённых файлов и методов, зоны риска.

{
  "diff_content": "unified diff string",
  "title": "Заголовок MR (необязательно)",
  "description": "Описание MR (необязательно)"
}

Ответ: summary, changed_files, additions, deletions, changed_methods, risk_areas.

Развёртывание через Helm

Для развёртывания CodeGraph рядом с экземпляром GitVerse:

helm install codegraph ./deploy/helm/codegraph \
  -f deploy/helm/codegraph/values-gitverse.yaml \
  --set secrets.gigachatAuthKey="<ключ_GigaChat>" \
  --set secrets.gitverseWebhookSecret="<секрет_вебхука>" \
  --set gitverse.oauthClientId="<oauth_client_id>" \
  --set secrets.gitverseOauthClientSecret="<oauth_client_secret>"
python scripts/validate_gitverse_deployment.py

Файл values-gitverse.yaml настраивает:

image:
  registry: ghcr.io
  repository: mkhlsavin/codegraph
  tag: latest

config:
  llmProvider: gigachat
  language: ru

gitverse:
  apiUrl: https://gitverse.ru/api/v1
  oauthClientId: ""
  oauthServerUrl: https://gitverse.ru

secrets:
  jwtSecret: ""
  gigachatAuthKey: ""
  gitverseWebhookSecret: ""
  gitverseOauthClientSecret: ""

Поддерживаемая topology для этого профиля:

  • service.type=ClusterIP за ingress
  • ingress route для /api и /dashboard
  • persistent PVC для CPG data и ChromaDB
  • GitVerse webhook secret и GitVerse OAuth client secret через Kubernetes Secret
  • GitVerse OAuth client ID и server URL через ConfigMap

Перед rollout проверьте профиль и wiring chart/runtime:

python scripts/validate_gitverse_deployment.py --strict

При развёртывании на закрытом контуре замените реестр образов и URL API:

--set gitverse.apiUrl="https://gitverse.internal.company.ru/api/v1"
--set gitverse.oauthServerUrl="https://gitverse.internal.company.ru"
--set image.registry="registry.internal.company.ru"

Deferred / Unsupported

G-10 / GigaCode context provider остаётся deferred. Сейчас CodeGraph не интегрируется с GigaCode как с внешним context provider, потому что это зависит от будущих extension API в GitVerse / GigaCode. В принятую область GitVerse-интеграции входят CI/CD, webhook, публикация review, OAuth, Web/CLI/MCP surface и on-prem deployment profile.

Устранение неполадок

Ошибка подписи вебхука (401/403)

401 Unauthorized – отсутствует заголовок подписи: - Убедитесь, что секретный ключ настроен в GitVerse - Проверьте, что Content-Type установлен в application/json

403 Forbidden – невалидная подпись: - Убедитесь, что секретный ключ в GitVerse совпадает с gitverse.webhook_secret в config.yaml - GitVerse может отправлять подпись как X-Hub-Signature-256 – CodeGraph принимает оба заголовка - Убедитесь, что прокси-серверы не изменяют тело запроса

400 Bad Request – устаревшая временна́я метка: - X-GitVerse-Timestamp старше 300 секунд - Проверьте синхронизацию часов между серверами GitVerse и CodeGraph

Ошибка перенаправления OAuth

  • Убедитесь, что OAUTH_GITVERSE_SERVER_URL указывает на корректный экземпляр
  • URL обратного вызова должен совпадать: https://<codegraph-host>/api/v1/auth/oauth/gitverse/callback
  • На закрытом контуре: проверьте сетевую доступность между CodeGraph и GitVerse

Недостаточные права API-токена

X-GitVerse-Token требует права на чтение содержимого репозитория и запросов на слияние. Создайте в GitVerse: Настройки → Токены доступа → Новый токен с областью repo:read.

Пустые результаты рецензирования

  • Убедитесь, что project_id использует формат owner/repo
  • Проверьте, что PR существует и открыт
  • Протестируйте токен: curl -sf https://<host>/api/v1/health -H "Authorization: Bearer <token>"

CI-конвейер не может подключиться к CodeGraph

  • CODEGRAPH_URL должен быть доступен из раннеров GitVerse
  • Проверка: curl -sf ${CODEGRAPH_URL}/api/v1/health

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