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
• Review Workflows
• 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¶

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:

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

1. Build CPG – gocpg parse in ghcr.io/mkhlsavin/codegraph:latest container
2. Security Scan – diff-based security analysis via /api/v1/security/scan-diff
3. PR Review – structural review via the GitVerse CLI/dashboard operator workflow
4. 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: |
          codegraph gitverse review-dry-run \
            --project-id "${{ github.repository }}" \
            --pr-number "${{ github.event.pull_request.number }}" \
            --token "${{ secrets.GITVERSE_TOKEN }}" \
            --format json > review-results.json

OAuth Authentication¶

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

Environment Variables¶

When OAUTH_GITVERSE_VAULT_PATH is set, CodeGraph reads the OAuth client id, secret and optional server URL from HashiCorp Vault. Explicit OAUTH_GITVERSE_CLIENT_ID, OAUTH_GITVERSE_CLIENT_SECRET and OAUTH_GITVERSE_SERVER_URL values take precedence for emergency override.

Minimal Vault KV v2 entry:

vault kv put secret/codegraph/oauth/gitverse \
  client_id="<gitverse-oauth-client-id>" \
  client_secret="<gitverse-oauth-client-secret>" \
  server_url="https://gitverse.ru"

Runtime Vault variables:

VAULT_ENABLED=true
VAULT_ADDR=http://vault.example.com:8200
VAULT_AUTH_METHOD=token
VAULT_SECRETS_MOUNT=secret
VAULT_TOKEN=<vault-token-with-read-access>
OAUTH_GITVERSE_VAULT_PATH=codegraph/oauth/gitverse

For local testing, register this callback URL:

http://127.0.0.1:8000/api/v1/auth/oauth/gitverse/callback

For production runtime, use the public API origin:

https://<codegraph-host>/api/v1/auth/oauth/gitverse/callback

Endpoints¶

OAuth uses parameterized routes that work for any configured provider:

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 client id and client secret are available from env or Vault. 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"

Verification and rotation¶

1. Restart the API after changing .env or Vault access policy.
2. Check discoverability:

bash curl -sf http://127.0.0.1:8000/api/v1/auth/oauth/providers | jq '.[] | select(.name=="gitverse")'

3. Verify that enabled=true and authorize_url contains state=.
4. Open /auth and sign in through GitVerse.
5. After secret rotation, update the Vault secret with the same keys, restart the API and rerun the discoverability/login smoke.

GitVerse webhooks and CPG auto-update are independent of OAuth login: for automatic update tracking keep using POST /api/v1/webhooks/gitverse and the HMAC secret from Webhook Configuration.

Review Workflows¶

Direct GitVerse review REST endpoints were retired under STORY-937. Use the GitVerse dashboard operator, repository review snapshot flow, MCP project-ops tool, or CLI command instead:

codegraph gitverse review-dry-run \
  --project-id owner/repo \
  --pr-number 42 \
  --token "$GITVERSE_TOKEN" \
  --format json

The workflow returns the same review result shape used by the dashboard and snapshot services:

{
  "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_integration_gitverse_review, codegraph_integration_gitverse_pr_info, codegraph_integration_gitverse_commit_status, codegraph_integration_gitverse_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 OpenViking
• 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