GitVerse Integration Guide

Integration guide for connecting CodeGraph with GitVerse (SberTech git hosting) for automated code review, security scanning, and technical debt tracking.

Table of Contents¶

Overview
Prerequisites
Docker Image Setup
Webhook Configuration
CI Pipeline
OAuth Authentication
REST API Endpoints
Helm Deployment
Troubleshooting
Next Steps

Overview¶

CodeGraph integrates with GitVerse (SberTech) for automated code review, security scanning, and technical debt tracking. Three integration paths:

CI/CD Pipeline – CodeGraph as a step in .gitverse/workflows/
Webhook-driven – push/PR events trigger CPG updates and reviews automatically
Standalone – deployed alongside GitVerse, accessed via REST API / CLI / MCP and the dedicated Web route /dashboard/gitverse

GitVerse uses GitHub-compatible webhook payloads (pull_request, head_commit). CodeGraph normalizes these automatically.

Prerequisites¶

CodeGraph instance (Docker or standalone) accessible from GitVerse runners
GitVerse account with API access and repo admin permissions (for webhooks)
Docker (for CI pipeline steps)
GigaChat API key (GIGACHAT_AUTH_KEY)

Docker Image Setup¶

Images published to GHCR via .github/workflows/publish-ghcr.yml, tagged on version tags (v*) and latest.

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

Includes GoCPG binary and supports 11 languages.

Webhook Configuration¶

Endpoint: POST /api/v1/webhooks/gitverse (returns 202 Accepted)

GitVerse setup: Repository Settings > Webhooks > Add Webhook: 1. URL: https://<codegraph-host>/api/v1/webhooks/gitverse 2. Content-Type: application/json 3. Secret: any string (for HMAC-SHA256 verification) 4. Events: Push and Pull Request

Signature Verification¶

CodeGraph verifies X-GitVerse-Signature (HMAC-SHA256). Falls back to X-Hub-Signature-256 for GitHub compatibility.

Error codes: - 401 Unauthorized – missing signature header - 403 Forbidden – invalid signature (HMAC mismatch)

Replay Protection¶

Webhooks include a X-GitVerse-Timestamp header (Unix epoch). CodeGraph validates that the timestamp is within 300 seconds (5 minutes) to prevent replay attacks. Stale webhooks are rejected with 400 Bad Request.

Supported Events¶

Event	Action
`push`	Incremental CPG update
`pull_request` (opened/synchronize)	Code review workflow

Configuration¶

Section gitverse in config.yaml:

gitverse:
  webhook_secret: ''            # HMAC-SHA256 secret
  auto_update_on_push: true     # Trigger CPG update on push events
  api_url: https://gitverse.ru/api/v1

CI Pipeline¶

Place the pipeline template at .gitverse/workflows/codegraph-review.yaml:

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

Required secrets/variables:

Name	Type	Description
`CODEGRAPH_URL`	Variable	CodeGraph API endpoint (e.g. `https://codegraph.example.com`)
`CODEGRAPH_API_TOKEN`	Secret	CodeGraph API authentication token
`PROJECT_LANGUAGE`	Variable	Source language (default: `python`)
`GITVERSE_TOKEN`	Secret	GitVerse API token (for PR review endpoint)

Stages (triggered on pull_request: opened, synchronize, reopened):

Build CPG – gocpg parse in ghcr.io/mkhlsavin/codegraph:latest container
Security Scan – diff-based security analysis via /api/v1/security/scan-diff
PR Review – structural review via /api/v1/review/gitverse
Report – aggregates results into job summary

Key pipeline fragment (full version in 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 Authentication¶

CodeGraph supports GitVerse OAuth for single sign-on via Sber ID.

Environment Variables¶

Variable	Description	Default
`OAUTH_GITVERSE_CLIENT_ID`	OAuth application ID	–
`OAUTH_GITVERSE_CLIENT_SECRET`	OAuth application secret	–
`OAUTH_GITVERSE_SERVER_URL`	GitVerse server base URL	`https://gitverse.ru`

Endpoints¶

OAuth uses parameterized routes that work for any configured provider:

Endpoint	Description
`GET /api/v1/auth/oauth/{provider}`	Initiates OAuth flow, redirects to provider authorization
`GET /api/v1/auth/oauth/{provider}/callback`	OAuth callback, exchanges code for JWT token

For GitVerse, use provider=gitverse: - Start: GET /api/v1/auth/oauth/gitverse - Callback: GET /api/v1/auth/oauth/gitverse/callback - Discoverability: GET /api/v1/auth/oauth/providers includes gitverse when configured

OAuth URL Construction¶

OAuth is auto-enabled when OAUTH_GITVERSE_CLIENT_ID is set. The provider constructs URLs from the server URL:

Authorize: {server_url}/oauth/authorize
Token: {server_url}/oauth/token
User info: {server_url}/api/v1/user

Sber ID Support¶

For organizations using Sber ID as identity provider, set OAUTH_GITVERSE_SERVER_URL to the corporate GitVerse instance URL, which proxies authorization through Sber ID:

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

REST API Endpoints¶

`POST /api/v1/review/gitverse` – Review PR¶

Fetches PR diff from GitVerse and runs structural code review (blast radius, complexity delta, dead code, security).

Headers: Authorization: Bearer <token>, X-GitVerse-Token: <gitverse-pat>

Request body:

{
  "project_id": "owner/repo",
  "pr_number": 42,
  "gitverse_url": "https://gitverse.ru/api/v1",
  "publish_review": true,
  "task_description": "Optional context",
  "dod_items": ["Tests pass", "No security issues"]
}

Response (ReviewResponse):

{
  "recommendation": "REQUEST_CHANGES",
  "score": 72.5,
  "findings": [
    {
      "category": "security",
      "severity": "high",
      "location": {"file": "src/auth.py", "line_start": 45},
      "message": "Unchecked user input passed to SQL query",
      "suggested_fix": "Use parameterized query"
    }
  ],
  "dod_validation": [
    {
      "description": "Tests pass",
      "satisfied": true,
      "evidence": "All 42 tests pass"
    }
  ],
  "summary": "Security and architecture issues found",
  "processing_time_ms": 3200.0,
  "request_id": "req_abc123",
  "metadata": {}
}

dod_validation is optional – returned only when dod_items are provided in the request, otherwise null.

Operator Surfaces¶

Web: /dashboard/gitverse productizes onboarding, project health, and audit drill-downs
CLI: codegraph gitverse status|bindings|template|review-dry-run
MCP: codegraph_gv_review, codegraph_gv_pr_info, codegraph_gv_commit_status, codegraph_gv_summary

Recommendation values: APPROVE, REQUEST_CHANGES, COMMENT, BLOCK.

`POST /api/v1/webhooks/gitverse` – Webhook Receiver¶

See Webhook Configuration.

`POST /api/v1/review/summary` – MR Summary¶

Generates a structured summary from any unified diff (platform-agnostic).

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

Response: summary, changed_files, additions, deletions, changed_methods, risk_areas.

Helm Deployment¶

For on-premise deployment alongside GitVerse:

helm install codegraph ./deploy/helm/codegraph \
  -f deploy/helm/codegraph/values-gitverse.yaml \
  --set secrets.gigachatAuthKey="your-gigachat-key" \
  --set secrets.gitverseWebhookSecret="your-webhook-secret" \
  --set gitverse.oauthClientId="your-oauth-client-id" \
  --set secrets.gitverseOauthClientSecret="your-oauth-client-secret"
python scripts/validate_gitverse_deployment.py

The values-gitverse.yaml overlay configures:

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: ""

Supported topology for this profile:

service.type=ClusterIP behind ingress
ingress route for /api and /dashboard
persistent PVCs for both CPG data and ChromaDB
GitVerse webhook secret and GitVerse OAuth client secret injected via Kubernetes Secret
GitVerse OAuth client ID and server URL injected via ConfigMap

Before rollout, validate the profile and chart/runtime wiring:

python scripts/validate_gitverse_deployment.py --strict

For on-premise GitVerse (air-gapped), override the API URL and image registry:

--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 remains deferred. CodeGraph does not currently integrate with GigaCode as an external context provider because that depends on future GitVerse / GigaCode extension APIs. The accepted GitVerse integration scope is CI/CD, webhook, review publication, OAuth, Web/CLI/MCP surface, and on-prem deployment profile.

Troubleshooting¶

Webhook Signature Error (401/403)¶

401 Unauthorized – signature header is missing: - Verify webhook secret is configured in GitVerse - Check Content-Type is application/json

403 Forbidden – signature is invalid: - Verify the webhook secret in GitVerse matches config.yaml > gitverse.webhook_secret - GitVerse may send signature as X-Hub-Signature-256 – CodeGraph accepts both headers - Ensure proxy servers do not modify the request body

400 Bad Request – timestamp expired: - X-GitVerse-Timestamp is too old (>300 seconds) - Check clock synchronization between GitVerse and CodeGraph servers

OAuth Redirect Fails¶

Confirm OAUTH_GITVERSE_SERVER_URL points to the correct instance
Redirect URI must match https://<codegraph-host>/api/v1/auth/oauth/gitverse/callback
On-premise: ensure network connectivity between CodeGraph and GitVerse

API Token Permissions¶

X-GitVerse-Token needs read access to repository contents and pull requests. Generate in GitVerse: Settings > Access Tokens > New Token with repo:read scope.

PR Review Returns Empty Results¶

Verify project_id uses owner/repo format
Check that the PR exists and is open
Test API token: curl -sf https://<host>/api/v1/health -H "Authorization: Bearer <token>"

CI Pipeline Cannot Reach CodeGraph¶

CODEGRAPH_URL must be reachable from GitVerse runners
Verify: curl -sf ${CODEGRAPH_URL}/api/v1/health

Next Steps¶

GigaChat Integration – LLM provider setup (required for code review)
Configuration – Full configuration reference
OpenCode Plugin – OpenCode integration
Yandex AI Studio Integration – Alternative LLM provider (larger context)
External Context – Linking CPG with external systems