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

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: CodeGraph verifies X-SourceCraft-Signature (HMAC-SHA256).

Config (config.yaml):

sourcecraft:
  webhook_secret: "your-webhook-secret-here"
  api_url: "https://api.sourcecraft.yandex.cloud"

Event	Action
`push` / `Push Hook`	Incremental CPG update
`merge_request` (opened/updated)	Code review workflow

CI Pipeline¶

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

cp ci/sourcecraft/codegraph-review.yaml .sourcecraft/ci.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`)
`WEBHOOK_SECRET`	Secret	Webhook secret for signature verification

Stages (triggered on merge_requests and main branch):

Build CPG (cpg-update) – gocpg parse in cr.yandex/${YCR_REGISTRY}/codegraph:latest container
Security Scan (security-scan) – diff-based security analysis via /api/v1/security/scan-diff, outputs SARIF for Security Dashboard
MR Review (mr-review) – structural review via /api/v1/review/sourcecraft
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¶

Endpoint	Description
`GET /api/v1/auth/oauth/providers`	Lists enabled OAuth providers (includes `sourcecraft` when configured)
`GET /api/v1/auth/oauth/sourcecraft`	Initiates OAuth flow, redirects to Yandex ID authorization
`GET /api/v1/auth/oauth/sourcecraft/callback`	OAuth callback, exchanges code for JWT token

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: recommendation (APPROVE/REQUEST_CHANGES/COMMENT/BLOCK), score (0-100), findings[], dod_validation[].

`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.

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_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

SourceCraft Integration Guide