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

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 / TUI

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: CodeGraph verifies X-GitVerse-Signature (HMAC-SHA256). Falls back to X-Hub-Signature-256 for GitHub compatibility.

Config (config.yaml):

gitverse:
  webhook_secret: "your-webhook-secret-here"
  api_url: "https://gitverse.ru/api/v1"

CI Pipeline¶

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

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 /api/v1/review/gitverse
4. Report – aggregates results into job summary

See ci/gitverse/codegraph-review.yaml for the full pipeline definition.

OAuth Authentication¶

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

Environment Variables¶

OAUTH_GITVERSE_CLIENT_ID=your-client-id
OAUTH_GITVERSE_CLIENT_SECRET=your-client-secret
OAUTH_GITVERSE_SERVER_URL=https://gitverse.ru   # default

Endpoints¶

Configuration in config.yaml¶

OAuth is auto-enabled when OAUTH_GITVERSE_CLIENT_ID is set. The provider constructs authorization, token, and userinfo URLs from the server URL:

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

For on-premise GitVerse instances, set OAUTH_GITVERSE_SERVER_URL to the internal URL.

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>

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

Response: recommendation (APPROVE/REQUEST_CHANGES/COMMENT/BLOCK), score (0-100), findings[], dod_validation[].

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"

The values-gitverse.yaml overlay sets GHCR image, GigaChat LLM, Russian language, and GitVerse API URL. For on-premise GitVerse, override the API URL:

--set gitverse.apiUrl="https://gitverse.internal.company.ru/api/v1"

Troubleshooting¶

Webhook Signature Mismatch (401)¶

• 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
• Check Content-Type is application/json

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
• REST API docs – Complete API documentation