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
• Review Workflows
• 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 service, MCP or CLI workflows
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.

Review Workflows¶

Direct SourceCraft review REST endpoints were retired under STORY-937. Use the review service through MCP, repository review snapshots, or CLI automation instead. The workflow still fetches MR diffs from SourceCraft and runs structural code review.

The workflow returns the shared ReviewResponse shape:

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