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

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

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

Содержание

Обзор

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

  1. Вебхуки – автоматическое обновление графа свойств кода (CPG) при каждом коммите и анализ запросов на слияние.
  2. CI-конвейер – шаг в pipeline GitVerse для сканирования безопасности, рецензирования кода и генерации отчётов.
  3. REST API – программный доступ к рецензированию PR и генерации описаний изменений.

Обе платформы поддерживают GigaChat как поставщика LLM, что обеспечивает полностью российский стек без зависимости от зарубежных сервисов.

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

Компонент Требование
CodeGraph Работающий экземпляр (Docker или локальная установка)
GitVerse Учётная запись с доступом к API репозитория
Docker Docker 20.10+ для запуска контейнера CodeGraph
Сеть Сетевая доступность между GitVerse и экземпляром CodeGraph

Docker-образ

Официальный Docker-образ CodeGraph публикуется в GitHub Container Registry:

ghcr.io/mkhlsavin/codegraph:latest

Сборка образа автоматизирована через GitHub Actions (.github/workflows/publish-ghcr.yml). Образ включает все компоненты: API-сервер, GoCPG-парсер, CLI-инструменты.

Проверка работоспособности:

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

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

Регистрация вебхука

Вебхук принимает события от GitVerse на конечной точке:

POST /api/v1/webhooks/gitverse

Для регистрации откройте параметры репозитория в GitVerse: Настройки репозитория –> Вебхуки –> Добавить вебхук. Укажите:

  • URL: https://<codegraph-host>/api/v1/webhooks/gitverse
  • Тип содержимого: application/json
  • Секретный ключ: произвольная строка для подписи HMAC-SHA256

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

Событие Описание Действие CodeGraph
push Отправка коммитов Инкрементальное обновление CPG
pull_request Создание или обновление PR Запуск анализа кода

Тип события определяется по заголовку X-GitVerse-Event (или совместимому X-GitHub-Event), а при его отсутствии – по структуре тела запроса (pull_request или head_commit/commits).

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

GitVerse подписывает тело запроса с помощью HMAC-SHA256. Подпись передаётся в заголовке:

X-GitVerse-Signature: sha256=<hex-digest>

CodeGraph верифицирует подпись, сравнивая её с вычисленным HMAC от тела запроса и настроенного секретного ключа. При несовпадении запрос отклоняется с кодом 401.

Конфигурация вебхуков

Секция 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)

Этапы анализа

Конвейер состоит из четырёх этапов, выполняемых при каждом запросе на слияние:

  1. Сборка CPG (cpg-update) – GoCPG анализирует исходный код и строит граф свойств кода в DuckDB.
  2. Сканирование безопасности (security-scan) – межпроцедурный анализ потоков данных по изменённому коду (diff).
  3. Рецензирование PR (pr-review) – оценка качества, зона поражения, рекомендации.
  4. Отчёт (report) – сводка результатов в артефактах задания.

Ключевой фрагмент конвейера (полная версия в 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 }}}' \
            -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

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

  1. Пользователь переходит на конечную точку авторизации CodeGraph:
GET /api/v1/auth/oauth/gitverse/authorize
  1. CodeGraph перенаправляет на страницу авторизации GitVerse:
https://gitverse.ru/oauth/authorize?client_id=...&scope=read:user,user:email
  1. После подтверждения GitVerse возвращает код авторизации.
  2. CodeGraph обменивает код на токен доступа через https://gitverse.ru/oauth/token.
  3. Данные пользователя запрашиваются через https://gitverse.ru/api/v1/user.

Поддержка Sber ID

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

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

REST API

Рецензирование PR

Конечная точка для рецензирования запроса на слияние в GitVerse:

POST /api/v1/review/gitverse

Заголовки:

Заголовок Описание
Authorization Bearer <codegraph_token>
X-GitVerse-Token Токен доступа GitVerse для получения diff

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

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

Пример ответа:

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

Приём вебхуков

POST /api/v1/webhooks/gitverse

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

Генерация описания MR

POST /api/v1/review/summary

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

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

Для развёртывания CodeGraph рядом с экземпляром GitVerse в инфраструктуре предприятия используется Helm-чарт с наложением параметров для GitVerse:

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

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

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

config:
  llmProvider: gigachat
  language: ru

gitverse:
  apiUrl: https://gitverse.ru/api/v1

secrets:
  gigachatAuthKey: ""
  gitverseWebhookSecret: ""

При развёртывании на закрытом контуре (без доступа в интернет) замените image.registry на адрес внутреннего реестра контейнеров и настройте config.llmProvider на локальную модель.

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

Ошибка проверки подписи вебхука

401 Unauthorized: Webhook signature verification failed

Причина: секретный ключ в настройках вебхука GitVerse не совпадает со значением gitverse.webhook_secret в config.yaml.

Решение: 1. Убедитесь, что секретный ключ одинаков в обоих местах. 2. Проверьте, что тело запроса передаётся без модификации (прокси-серверы не должны изменять содержимое).

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

400 Bad Request: redirect_uri mismatch

Причина: URL обратного вызова, зарегистрированный в OAuth-приложении GitVerse, не совпадает с адресом экземпляра CodeGraph.

Решение: 1. В настройках OAuth-приложения GitVerse укажите URL: https://<codegraph-host>/api/v1/auth/oauth/gitverse/callback. 2. Убедитесь, что OAUTH_GITVERSE_SERVER_URL указывает на корректный адрес GitVerse.

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

403 Forbidden: insufficient scope

Причина: токен GitVerse не имеет прав на чтение содержимого репозитория или запросов на слияние.

Решение: 1. Создайте токен с правами read:repository и read:pull_request (или аналогичными). 2. Передайте токен в заголовке X-GitVerse-Token при вызове /api/v1/review/gitverse.

Конвейер не запускается

Причина: файл конвейера расположен не в корректном каталоге или имеет синтаксические ошибки.

Решение: 1. Убедитесь, что файл находится по пути .gitverse/workflows/codegraph-review.yaml. 2. Проверьте, что переменные CODEGRAPH_URL и CODEGRAPH_API_TOKEN заданы в настройках репозитория.

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