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

Руководство по подключению CodeGraph к GitHub для автоматизированного код-ревью, сканирования безопасности и инкрементального обновления CPG.

Содержание¶

• Обзор
• Предварительные требования
• Настройка вебхуков
• Конвейер CI (GitHub Actions)
• Конечные точки REST API
• Инструменты MCP
• Инкрементальное обновление CPG
• Настройка Docker-образа
• Устранение неполадок
• Дальнейшие шаги

Обзор¶

CodeGraph интегрируется с GitHub для автоматизированного код-ревью, сканирования безопасности и отслеживания технического долга. Три варианта интеграции:

• Конвейер CI/CD – CodeGraph как шаг в рабочих процессах GitHub Actions
• На основе вебхуков – события push/PR автоматически запускают инкрементальное обновление CPG и ревью
• Автономный режим – развёртывание рядом с GitHub, доступ через REST API / CLI / MCP

Данные вебхуков GitHub нормализуются CodeGraph в унифицированные модели UnifiedPushEvent и UnifiedMREvent, общие для всех 4 поддерживаемых платформ.

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

• Экземпляр CodeGraph (Docker или автономный), доступный из GitHub (или самостоятельно размещённых раннеров)
• Репозиторий GitHub с правами администратора (для настройки вебхуков)
• Docker (для шагов конвейера CI)
• Ключ API LLM: YANDEX_API_KEY, GIGACHAT_AUTH_KEY или OPENAI_API_KEY

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

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

Настройка в GitHub: Repository Settings > Webhooks > Add webhook: 1. Payload URL: https://<codegraph-host>/api/v1/webhooks/github 2. Content type: application/json 3. Secret: произвольная строка (для верификации HMAC-SHA256) 4. Events: выберите Pushes и Pull requests (или “Let me select individual events”)

Верификация подписи¶

CodeGraph проверяет заголовок X-Hub-Signature-256 (HMAC-SHA256, формат: sha256=<hex>).

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

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

События, не соответствующие этим типам, возвращаются со статусом {"status": "skipped"}.

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

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

github:
  webhook_secret: "your-github-webhook-secret"
  auto_update_on_push: true    # trigger incremental CPG update on push events

Определение типа события¶

CodeGraph определяет тип события по заголовку X-GitHub-Event. Если заголовок отсутствует (например, при тестировании через curl), используется определение по структуре полезной нагрузки:

• присутствует ключ pull_request – событие pull_request
• присутствует head_commit или (ref + commits) – событие push
• присутствует ключ zen – событие ping

Конвейер CI (GitHub Actions)¶

Базовый рабочий процесс¶

Создайте .github/workflows/codegraph-review.yaml:

name: CodeGraph Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

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' }}

  security-scan:
    name: Security Scan
    needs: cpg-update
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/mkhlsavin/codegraph:latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Diff-based security scan
        run: |
          DIFF=$(git diff ${{ github.event.pull_request.base.sha }}...HEAD)
          curl -sf -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()))'), \"output_format\": \"sarif\"}" \
            -o security-results.sarif
        env:
          CODEGRAPH_URL: ${{ vars.CODEGRAPH_URL }}
          CODEGRAPH_TOKEN: ${{ secrets.CODEGRAPH_API_TOKEN }}
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: security-results.sarif

Необходимые секреты и переменные¶

Интеграция с SARIF¶

CodeGraph может выводить результаты сканирования безопасности в формате SARIF, совместимом с GitHub Code Scanning:

curl -sf -X POST "${CODEGRAPH_URL}/api/v1/security/scan-diff" \
  -H "Authorization: Bearer ${CODEGRAPH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"diff_content": "...", "output_format": "sarif"}' \
  -o security-results.sarif

Загрузите SARIF-файл с помощью github/codeql-action/upload-sarif@v3, чтобы результаты отобразились во вкладке Security репозитория GitHub.

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

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

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

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

Сканирует необработанный унифицированный 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": "User input concatenated into SQL query",
      "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/review/summary – Сводка по PR¶

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

{
  "diff_content": "unified diff string",
  "title": "Optional PR title",
  "description": "Optional PR description"
}

Ответ: 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.

POST /api/v1/review/pr – Ревью GitHub PR¶

Выполняет ревью GitHub PR напрямую, получая diff через GitHub API (не нужно передавать raw diff).

{
  "owner": "org",
  "repo": "repo",
  "pr_number": 42,
  "task_description": "Optional review focus",
  "dod_items": ["No security issues", "Tests pass"]
}

Требует заголовок X-GitHub-Token с токеном доступа GitHub, имеющим права на чтение репозитория.

Ответ: recommendation, score, findings[], dod_validation[], summary, processing_time_ms, request_id.

GET /api/v1/webhooks/status/{project_id} – Статус обновления¶

Возвращает текущий статус конвейера обновления CPG для проекта.

{
  "project_id": "my-project",
  "last_update": "2026-03-09T12:00:00+00:00",
  "status": "completed",
  "commit_sha": "abc12345",
  "duration_ms": 1234,
  "gocpg_status": "completed",
  "chromadb_synced": 3,
  "error": null
}

Инструменты MCP¶

Когда CodeGraph работает как MCP-сервер (python -m src.mcp), ИИ-агенты могут использовать инструменты, работающие с CPG:

Интеграция с OpenCode¶

Добавьте в opencode.json для использования инструментов CodeGraph в OpenCode:

{
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["python", "-m", "src.mcp", "--transport", "stdio"]
    }
  }
}

Инкрементальное обновление CPG¶

При получении события push через вебхук CodeGraph запускает полный конвейер инкрементального обновления:

1. Определение проекта – сопоставление по project_id, URL репозитория или активному проекту
2. Обновление GoCPG – инкрементальное обновление CPG через gRPC/подпроцесс (from_commit -> to_commit)
3. Синхронизация ChromaDB – обновление коллекций векторного хранилища для изменённых файлов
4. Уведомление через WebSocket – рассылка события cpg.update.complete подключённым клиентам

Поведение конвейера: - Дублирующиеся события push (один проект + один SHA коммита) дедуплицируются - Быстрые последовательные push в один проект объединяются (слияние изменённых файлов, последний коммит) - При сбое GoCPG автоматически выполняется повторная попытка через 60 секунд - Синхронизация ChromaDB продолжается даже при сбое обновления GoCPG - Вебхук всегда немедленно возвращает 202 Accepted (обработка выполняется асинхронно)

Отслеживайте статус конвейера через GET /api/v1/webhooks/status/{project_id}.

Настройка Docker-образа¶

Образы публикуются в GHCR через .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 языков (C, C++, C#, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, TypeScript).

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

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

401 Unauthorized – отсутствует заголовок X-Hub-Signature-256: - Убедитесь, что секрет вебхука настроен в GitHub - Проверьте, что Content-Type установлен в application/json

403 Forbidden – подпись недействительна: - Убедитесь, что секрет вебхука в GitHub совпадает с config.yaml > github.webhook_secret - Убедитесь, что прокси-серверы не модифицируют тело запроса

Вебхук возвращает 400¶

• Проверьте, что полезная нагрузка является валидным JSON
• Для событий push убедитесь, что присутствует массив commits

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

• CODEGRAPH_URL должен быть доступен из раннеров GitHub Actions
• Проверка: curl -sf ${CODEGRAPH_URL}/api/v1/health
• Для самостоятельно размещённых раннеров: проверьте правила межсетевого экрана и подключение VPN

Загрузка SARIF завершается ошибкой¶

• Убедитесь, что файл имеет валидный формат SARIF (используйте output_format: "sarif" в запросе scan-diff)
• GitHub Code Scanning требует включения GitHub Advanced Security для репозитория (для приватных репозиториев)

Инкрементальное обновление показывает “unavailable”¶

• Убедитесь, что GoCPG установлен и доступен: gocpg --version
• Проверьте, что переменная окружения GOCPG_PATH указывает на бинарный файл GoCPG
• Просмотрите журналы: grep "GoCPG" /var/log/codegraph/*.log

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

• Интеграция с GitLab – интеграция через вебхуки и CI GitLab
• Интеграция с SourceCraft – интеграция с Yandex SourceCraft
• Интеграция с GitVerse – интеграция с SberTech GitVerse
• Конфигурация – полный справочник по конфигурации
• Документация REST API – полная документация API