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

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

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

Содержание

Обзор

SourceCraft – платформа размещения git-репозиториев от Yandex Cloud. CodeGraph интегрируется с SourceCraft по трём направлениям:

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

Обе платформы полностью совместимы с экосистемой Yandex Cloud: YandexGPT как поставщик LLM, Yandex Container Registry для образов, Managed Kubernetes для развёртывания.

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

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

Docker-образ

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

cr.yandex/${YCR_REGISTRY}/codegraph:latest

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

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

docker pull cr.yandex/${YCR_REGISTRY}/codegraph:latest
docker run --rm cr.yandex/${YCR_REGISTRY}/codegraph:latest python -m src.cli health

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

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

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

POST /api/v1/webhooks/sourcecraft

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

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

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

Событие Описание Действие CodeGraph
push / Push Hook Отправка коммитов Инкрементальное обновление CPG
merge_request / Merge Request Hook Создание или обновление MR Запуск анализа кода

Тип события определяется по заголовку X-SourceCraft-Event (или совместимому X-Gitlab-Event), а при его отсутствии – по структуре тела запроса (merge_request/object_attributes или commits/before/after).

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

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

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

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

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

Секция sourcecraft в файле config.yaml:

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

CI-конвейер

Шаблон конвейера

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

cp ci/sourcecraft/codegraph-review.yaml .sourcecraft/ci.yaml

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

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

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

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

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

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

stages:
  - analyze
  - review
  - report

cpg-update:
  stage: analyze
  image: cr.yandex/${YCR_REGISTRY}/codegraph:latest
  script:
    - gocpg parse --input=. --output=/tmp/cpg.duckdb --lang=${PROJECT_LANGUAGE:-python}
  only:
    - merge_requests
    - main

mr-review:
  stage: review
  image: cr.yandex/${YCR_REGISTRY}/codegraph:latest
  script:
    - |
      curl -s -X POST "${CODEGRAPH_URL}/api/v1/review/sourcecraft" \
        -H "Authorization: Bearer ${CODEGRAPH_TOKEN}" \
        -H "X-SourceCraft-Token: ${CI_JOB_TOKEN}" \
        -H "Content-Type: application/json" \
        -d '{"project_id": "${CI_PROJECT_ID}", "mr_iid": ${CI_MERGE_REQUEST_IID}}'
  only:
    - merge_requests

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

CodeGraph поддерживает OAuth-авторизацию через SourceCraft для единого входа (SSO) с использованием Yandex ID.

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

Переменная Описание Значение по умолчанию
OAUTH_SOURCECRAFT_CLIENT_ID Идентификатор OAuth-приложения –
OAUTH_SOURCECRAFT_CLIENT_SECRET Секрет OAuth-приложения –
OAUTH_SOURCECRAFT_SERVER_URL Базовый URL сервера Yandex ID https://oauth.yandex.ru

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

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

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

OAuth включается автоматически при установке OAUTH_SOURCECRAFT_CLIENT_ID. URL конечных точек:

  • Авторизация: {server_url}/authorize (по умолчанию https://oauth.yandex.ru/authorize)
  • Токен: {server_url}/token (по умолчанию https://oauth.yandex.ru/token)
  • Информация о пользователе: https://login.yandex.ru/info

Области доступа (scopes): login:email, login:info.

Для корпоративных экземпляров с собственным Yandex ID измените OAUTH_SOURCECRAFT_SERVER_URL.

Yandex Cloud IAM

CodeGraph поддерживает аутентификацию по IAM-токенам Yandex Cloud в качестве альтернативы JWT. Этот способ удобен для сервисных аккаунтов и автоматизированных конвейеров, работающих в Yandex Cloud.

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

IAM_ENABLED=true
IAM_VALIDATION_URL=https://iam.api.cloud.yandex.net/iam/v1/tokens

Использование

Передайте IAM-токен в заголовке X-YC-IAM-Token:

curl -sf https://<codegraph-host>/api/v1/health \
  -H "X-YC-IAM-Token: <iam-token>"

Токены кэшируются с TTL 5 минут для снижения нагрузки на API проверки.

REST API

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

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

POST /api/v1/review/sourcecraft

Заголовки:

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

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

{
  "project_id": "proj-123",
  "mr_iid": 42,
  "sourcecraft_url": "https://api.sourcecraft.yandex.cloud",
  "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/sourcecraft

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

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

POST /api/v1/review/summary

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

Генерация сообщения коммита

POST /api/v1/review/commit-message

Принимает diff_content и генерирует сообщение коммита в формате Conventional Commits: message, type, scope, files_changed.

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

Для развёртывания CodeGraph в Yandex Cloud Managed Kubernetes (MK8s) рядом с экземпляром SourceCraft используется Helm-чарт:

helm install codegraph ./deploy/helm/codegraph \
  --set image.repository="${YCR_REGISTRY}/codegraph" \
  --set secrets.yandexApiKey="<ключ_API_Yandex>" \
  --set secrets.yandexFolderId="<идентификатор_каталога>"

Базовый файл values.yaml предварительно настроен для экосистемы Yandex Cloud:

image:
  registry: cr.yandex
  repository: ""  # Установите YCR_REGISTRY/codegraph
  tag: latest

config:
  llmProvider: yandex
  language: en

Для русского языка и GigaChat:

helm install codegraph ./deploy/helm/codegraph \
  --set config.llmProvider=gigachat \
  --set config.language=ru \
  --set secrets.gigachatAuthKey="<ключ_GigaChat>"

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

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

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

403 Forbidden: Invalid webhook signature

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

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

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

400 Bad Request: redirect_uri mismatch

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

Решение: 1. В консоли Yandex ID укажите URL обратного вызова: https://<codegraph-host>/api/v1/auth/oauth/sourcecraft/callback. 2. Убедитесь, что OAUTH_SOURCECRAFT_SERVER_URL указывает на корректный адрес.

Ошибка IAM-токена

401 Unauthorized: IAM token validation failed

Причина: IAM-токен недействителен или аутентификация IAM отключена.

Решение: 1. Убедитесь, что установлена переменная IAM_ENABLED=true. 2. Проверьте, что сервисный аккаунт имеет необходимые роли в Yandex Cloud IAM. 3. Проверьте сетевую доступность iam.api.cloud.yandex.net.

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

403 Forbidden: insufficient scope

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

Решение: 1. Создайте токен проекта с правами чтения в SourceCraft. 2. Передайте токен в заголовке X-SourceCraft-Token при вызове /api/v1/review/sourcecraft.

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

Причина: переменная CODEGRAPH_URL не задана или CodeGraph недоступен из сети CI-раннеров.

Решение: 1. Проверьте: curl -sf ${CODEGRAPH_URL}/api/v1/health. 2. В Yandex Cloud убедитесь, что VPC-сеть и группы безопасности разрешают трафик на порт 8000.

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