SourceCraft Integration Guide

Integration guide for connecting CodeGraph with SourceCraft (Yandex Cloud 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
• Yandex Cloud IAM
• REST API Endpoints
• MCP Tools
• Helm Deployment
• Troubleshooting

Overview¶

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

• CI/CD Pipeline – CodeGraph as a step in .sourcecraft/ci.yaml
• Webhook-driven – push/MR events trigger CPG updates and reviews automatically
• Standalone – deployed alongside SourceCraft, accessed via REST API / CLI / MCP

SourceCraft uses GitLab-compatible webhook payloads (merge_request, commits). CodeGraph normalizes these automatically.

Prerequisites¶

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

Docker Image Setup¶

Images published to Yandex Container Registry (YCR) via .github/workflows/publish-ycr.yml, tagged on version tags (v*) and latest.

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

Includes GoCPG binary and supports 11 languages.

Webhook Configuration¶

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

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

Signature verification: CodeGraph verifies X-SourceCraft-Signature header (HMAC-SHA256, format: sha256=<hex>).

Replay attack protection: CodeGraph validates X-SourceCraft-Timestamp header — requests older than 5 minutes are rejected with 400 Bad Request. Failed replays are logged to the audit log.

Config (config.yaml):

sourcecraft:
  webhook_secret: "your-webhook-secret-here"
  auto_update_on_push: true    # trigger incremental CPG update on push events
  api_url: "https://api.sourcecraft.yandex.cloud"

CI Pipeline¶

Place the pipeline template at .sourcecraft/ci.yaml:

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

Required secrets/variables:

Note: Inside the CI pipeline, CODEGRAPH_API_URL is mapped to CODEGRAPH_URL and CODEGRAPH_API_TOKEN to CODEGRAPH_TOKEN.

Stages (triggered on merge_requests and main branch):

1. Build CPG (cpg-update) – gocpg parse in cr.yandex/${YCR_REGISTRY}/codegraph:latest container
2. Security Scan (security-scan) – diff-based security analysis via /api/v1/security/scan-diff, outputs SARIF for Security Dashboard
3. MR Review (mr-review) – structural review via /api/v1/review/sourcecraft
4. Report (report) – aggregates results summary

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

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

OAuth Authentication¶

CodeGraph supports SourceCraft OAuth for single sign-on via Yandex ID.

Environment Variables¶

OAUTH_SOURCECRAFT_CLIENT_ID=your-client-id
OAUTH_SOURCECRAFT_CLIENT_SECRET=your-client-secret
OAUTH_SOURCECRAFT_SERVER_URL=https://oauth.yandex.ru   # default

Endpoints¶

Configuration in config.yaml¶

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

• Authorize: {server_url}/authorize (default: https://oauth.yandex.ru/authorize)
• Token: {server_url}/token (default: https://oauth.yandex.ru/token)
• User info: https://login.yandex.ru/info

Scopes: login:email, login:info.

For on-premise SourceCraft instances with custom Yandex ID, override OAUTH_SOURCECRAFT_SERVER_URL.

Yandex Cloud IAM¶

CodeGraph supports Yandex Cloud IAM token authentication as an alternative to JWT. This is useful for service accounts and automated pipelines running in Yandex Cloud.

Configuration¶

IAM_ENABLED=true
IAM_VALIDATION_URL=https://iam.api.cloud.yandex.net/iam/v1/tokens

Usage¶

Pass the IAM token in the X-YC-IAM-Token header:

curl -sf https://<codegraph-host>/api/v1/health \
  -H "X-YC-IAM-Token: <iam-token>"

Tokens are cached with a 5-minute TTL to minimize validation API calls.

REST API Endpoints¶

POST /api/v1/review/sourcecraft – Review MR¶

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

Headers: 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": "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": [
    {"item": "Tests pass", "status": "passed"},
    {"item": "No security issues", "status": "failed"}
  ],
  "summary": "Security and architecture issues found",
  "processing_time_ms": 3200.0,
  "request_id": "req_abc123",
  "metadata": {}
}

POST /api/v1/security/scan-diff – Security Scan¶

Scans a raw unified diff for security vulnerabilities without git subprocess. Used by CI pipeline for diff-based security analysis.

Request (ScanDiffRequest):

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

Response (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/webhooks/sourcecraft – 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.

POST /api/v1/review/commit-message – Commit Message¶

Generates a conventional commit message from a diff.

{
  "diff_content": "unified diff string"
}

Response: message, type, scope, files_changed.

MCP Tools¶

CodeGraph provides 8 MCP tools for SourceCraft integration, registered in src/mcp/tools/sourcecraft.py:

These tools are available when CodeGraph runs as an MCP server (python -m src.mcp).

Helm Deployment¶

For on-premise deployment alongside SourceCraft in Yandex Cloud Managed Kubernetes (MK8s):

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"

The default values.yaml is configured for SourceCraft / Yandex Cloud:

image:
  registry: cr.yandex
  repository: ""  # Set to YCR_REGISTRY/codegraph
  tag: latest

config:
  llmProvider: yandex
  language: en

For Russian language and GigaChat LLM:

helm install codegraph ./deploy/helm/codegraph \
  --set config.llmProvider=gigachat \
  --set config.language=ru \
  --set secrets.gigachatAuthKey="your-gigachat-key"

Troubleshooting¶

Webhook Signature Mismatch (401)¶

• Verify the webhook secret in SourceCraft matches config.yaml > sourcecraft.webhook_secret
• Check X-SourceCraft-Signature header is present in requests
• Check Content-Type is application/json

OAuth Redirect Fails¶

• Confirm OAUTH_SOURCECRAFT_SERVER_URL points to the correct Yandex ID instance
• Redirect URI must match https://<codegraph-host>/api/v1/auth/oauth/sourcecraft/callback
• Verify the OAuth app is registered with correct redirect URIs in Yandex ID console

API Token Permissions¶

X-SourceCraft-Token needs read access to repository contents and merge requests. Generate a project token in SourceCraft with appropriate read permissions.

MR Review Returns Empty Results¶

• Verify project_id matches the SourceCraft project identifier
• Check that the MR exists and is open
• Test API token: curl -sf https://<host>/api/v1/health -H "Authorization: Bearer <token>"

CI Pipeline Cannot Reach CodeGraph¶

• CODEGRAPH_API_URL must be reachable from SourceCraft CI runners
• Verify: curl -sf ${CODEGRAPH_URL}/api/v1/health
• In Yandex Cloud: ensure VPC network and security groups allow traffic on port 8000

IAM Token Validation Fails¶

• Ensure IAM_ENABLED=true is set
• Check that the service account has necessary roles in Yandex Cloud IAM
• Verify network connectivity to iam.api.cloud.yandex.net

Next Steps¶

• Yandex AI Studio Integration – LLM provider setup
• GigaChat Integration – Alternative Russian LLM provider
• Configuration – Full configuration reference
• REST API docs – Complete API documentation