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

Как подключить CodeGraph к SourceCraft, чтобы автоматически обновлять CPG, запускать анализ изменений и получать отчёты по качеству и безопасности.

Содержание¶

• Обзор
• Предварительные требования
• Docker-образ
• Настройка вебхуков
• CI-конвейер
• OAuth-аутентификация
• Yandex Cloud IAM
• REST API
• MCP-инструменты
• Развёртывание через Helm
• Устранение неполадок

Обзор¶

Интеграция с SourceCraft (Yandex Cloud) покрывает три основных сценария:

• CI/CD-конвейер — CodeGraph запускается как шаг в .sourcecraft/ci.yaml
• Вебхуки — события push и MR автоматически обновляют CPG и инициируют анализ
• Автономный режим — CodeGraph развёрнут рядом с SourceCraft и доступен через REST API, CLI и MCP

SourceCraft использует формат вебхуков, совместимый с GitLab (merge_request, commits). CodeGraph нормализует их автоматически.

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

• Экземпляр CodeGraph (Docker или локальная установка), доступный из CI-раннеров SourceCraft
• Учётная запись SourceCraft с доступом к API и правами администратора репозитория (для вебхуков)
• Docker (для шагов CI-конвейера)
• API-ключ Yandex Cloud (YANDEX_API_KEY) или API-ключ GigaChat (GIGACHAT_AUTH_KEY)

Docker-образ¶

Образы публикуются в Yandex Container Registry (YCR) через .github/workflows/publish-ycr.yml, тегируются по тегам версий (v*) и latest.

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

Включает бинарный файл GoCPG и поддерживает 11 языков программирования.

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

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

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

Проверка подписи: CodeGraph верифицирует заголовок X-SourceCraft-Signature (HMAC-SHA256, формат: sha256=<hex>).

Защита от повторных запросов: CodeGraph проверяет заголовок X-SourceCraft-Timestamp — запросы старше 5 минут отклоняются с кодом 400 Bad Request. Неудачные попытки повтора регистрируются в журнале аудита.

Конфигурация (config.yaml):

sourcecraft:
  webhook_secret: "your-webhook-secret-here"
  auto_update_on_push: true    # обновлять CPG при событии push
  api_url: "https://api.sourcecraft.yandex.cloud"

CI-конвейер¶

Скопируйте шаблон конвейера в .sourcecraft/ci.yaml:

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

Обязательные секреты и переменные:

Примечание: Внутри CI-конвейера CODEGRAPH_API_URL маппится в CODEGRAPH_URL, а CODEGRAPH_API_TOKEN в CODEGRAPH_TOKEN.

Этапы (запускаются при merge_requests и ветке main):

1. Сборка CPG (cpg-update) – gocpg parse в контейнере cr.yandex/${YCR_REGISTRY}/codegraph:latest
2. Сканирование безопасности (security-scan) – анализ безопасности на основе diff через /api/v1/security/scan-diff, вывод в формате SARIF для панели безопасности
3. Рецензирование MR (mr-review) – структурный анализ через /api/v1/review/sourcecraft
4. Отчёт (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

security-scan:
  stage: review
  image: cr.yandex/${YCR_REGISTRY}/codegraph:latest
  script:
    - |
      DIFF=$(git diff ${CI_MERGE_REQUEST_DIFF_BASE_SHA}...HEAD)
      curl -s -X POST "${CODEGRAPH_URL}/api/v1/security/scan-diff" \
        -H "Authorization: Bearer ${CODEGRAPH_TOKEN}" \
        -H "Content-Type: application/json" \
        -d "{\"diff_content\": $(echo "$DIFF" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')}" \
        -o security-results.json
  artifacts:
    reports:
      sast: gl-sast-report.json
  only:
    - merge_requests

Полное определение конвейера см. в ci/sourcecraft/codegraph-review.yaml.

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

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

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

OAUTH_SOURCECRAFT_CLIENT_ID=your-client-id
OAUTH_SOURCECRAFT_CLIENT_SECRET=your-client-secret
OAUTH_SOURCECRAFT_SERVER_URL=https://oauth.yandex.ru   # по умолчанию

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

Конфигурация в config.yaml¶

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

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

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

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

Yandex Cloud IAM¶

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

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

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¶

POST /api/v1/review/sourcecraft – Рецензирование MR¶

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

Заголовки: Authorization: Bearer <token>, X-SourceCraft-Token: <sourcecraft-or-iam-token>

{
  "project_id": "proj-123",
  "mr_iid": 42,
  "sourcecraft_url": "https://api.sourcecraft.yandex.cloud",
  "task_description": "Необязательный контекст задачи",
  "dod_items": ["Тесты проходят", "Нет проблем безопасности"]
}

Ответ (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": [
    {"item": "Тесты проходят", "status": "passed"},
    {"item": "Нет проблем безопасности", "status": "failed"}
  ],
  "summary": "Обнаружены проблемы безопасности и архитектуры",
  "processing_time_ms": 3200.0,
  "request_id": "req_abc123",
  "metadata": {}
}

POST /api/v1/security/scan-diff – Сканирование безопасности¶

Сканирует необработанный unified diff на предмет уязвимостей безопасности без подпроцесса git. Используется CI-конвейером для анализа безопасности на основе diff.

Запрос (ScanDiffRequest):

{
  "diff_content": "unified diff string",
  "output_format": "json"
}

Ответ (ScanDiffResponse):

{
  "findings": [
    {
      "finding_id": "f-001",
      "pattern_id": "CWE-89",
      "pattern_name": "SQL Injection",
      "category": "security",
      "severity": "high",
      "method_name": "execute_query",
      "filename": "src/db.py",
      "line_number": 42,
      "description": "Пользовательский ввод конкатенирован в SQL-запрос",
      "cwe_ids": ["CWE-89"],
      "confidence": 0.92
    }
  ],
  "sarif": {},
  "new_count": 1,
  "fixed_count": 0,
  "total_count": 1,
  "critical_count": 0,
  "high_count": 1,
  "medium_count": 0,
  "low_count": 0
}

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

См. раздел Настройка вебхуков.

POST /api/v1/review/summary – Описание MR¶

Генерирует структурированное описание из любого unified diff (платформенно-независимый).

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

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

POST /api/v1/review/commit-message – Сообщение коммита¶

Генерирует сообщение коммита в формате Conventional Commits из diff.

{
  "diff_content": "unified diff string"
}

Ответ: message, type, scope, files_changed.

MCP-инструменты¶

CodeGraph предоставляет 8 MCP-инструментов для интеграции с SourceCraft, зарегистрированных в src/mcp/tools/sourcecraft.py:

Эти инструменты доступны при запуске CodeGraph как MCP-сервера (python -m src.mcp).

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

Для развёртывания CodeGraph в Yandex Cloud Managed Kubernetes (MK8s) рядом с SourceCraft:

helm install codegraph ./deploy/helm/codegraph \
  --set image.repository="${YCR_REGISTRY}/codegraph" \
  --set secrets.yandexApiKey="your-yandex-api-key" \
  --set secrets.yandexFolderId="your-folder-id"

Файл values.yaml по умолчанию настроен для SourceCraft / 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="your-gigachat-key"

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

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

• Убедитесь, что секрет вебхука в SourceCraft совпадает с config.yaml > sourcecraft.webhook_secret
• Проверьте наличие заголовка X-SourceCraft-Signature в запросах
• Проверьте, что Content-Type равен application/json

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

• Убедитесь, что OAUTH_SOURCECRAFT_SERVER_URL указывает на правильный экземпляр Yandex ID
• URI перенаправления должен совпадать с https://<codegraph-host>/api/v1/auth/oauth/sourcecraft/callback
• Проверьте, что OAuth-приложение зарегистрировано с корректными URI перенаправления в консоли Yandex ID

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

X-SourceCraft-Token требует права чтения содержимого репозитория и запросов на слияние. Создайте токен проекта в SourceCraft с соответствующими правами чтения.

Рецензирование MR возвращает пустые результаты¶

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

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

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

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

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

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

• Интеграция с Yandex AI Studio – Настройка поставщика LLM
• Интеграция с GigaChat – Альтернативный российский поставщик LLM
• Конфигурация – Полный справочник конфигурации
• REST API – Полная документация API