Federation

Federation (v6.3)

Federation enables cross-repository queries and unified visibility across multiple codebases. Transform CKB from a single-repo tool into an organizational code intelligence platform.

v6.3 Theme: Contract-Aware Impact Analysis — cross-repo intelligence through explicit API boundaries

What is Federation?

A federation is a named collection of repositories that can be queried together. Instead of analyzing each repo in isolation, federation lets you:

Search for modules across all your microservices
Find ownership patterns across the organization
Identify hotspots spanning multiple repositories
Track architectural decisions at the org level

Quick Start

# Create a federation
ckb federation create platform --description "Our microservices platform"

# Add repositories
ckb federation add platform --repo-id=api --path=/code/api-service
ckb federation add platform --repo-id=auth --path=/code/auth-service
ckb federation add platform --repo-id=web --path=/code/web-app

# Sync the federation index
ckb federation sync platform

# Check status
ckb federation status platform

Core Concepts

Repository Identity

Each repository in a federation has two identifiers:

Identifier	Description	Mutable?
repo_uid	UUID generated on first add	No - permanent
repo_id	Human-readable alias	Yes - can rename

The UUID ensures stable references even if you rename repositories:

# Rename without breaking references
ckb federation rename platform old-api api

Federation Index

When you sync a federation, CKB extracts summaries from each repository's database and stores them in a unified index:

Modules - Name, responsibility, owner, tags
Ownership - Path patterns and owners
Hotspots - Top 20 per repo by score
Decisions - ADRs with status and affected modules

This index enables fast cross-repo queries without opening each database.

Schema Compatibility

Federation requires repositories with schema version 6 or higher. Check compatibility:

ckb federation status platform
# Shows: Compatible: 3/4

# See details
ckb federation repos platform --json

For incompatible repos, the fix is:

cd /path/to/repo
ckb refresh --migrate

Staleness Propagation

Federation staleness follows "weakest link" semantics - a federation is only as fresh as its stalest repository.

Level	Meaning
fresh	All repos synced within 24 hours
aging	Some repos 1-7 days old
stale	Some repos 7-30 days old
obsolete	Some repos over 30 days old

Query results include staleness information so you know when to refresh.

CLI Commands

Create a Federation

ckb federation create <name> [--description "..."]

Creates a new federation with the given name. Federations are stored in ~/.ckb/federation/<name>/.

Delete a Federation

ckb federation delete <name> [--force]

Deletes a federation and its index. Use --force to skip confirmation.

List Federations

ckb federation list [--json]

Lists all available federations.

Federation Status

ckb federation status <name> [--json]

Shows federation details:

Name and description
Creation date
Number of repositories
Compatibility status
Per-repo sync status

Add Repository

ckb federation add <federation> --repo-id=<id> --path=<path> [--tags=tag1,tag2]

Adds a repository to the federation. The path must be an absolute path to a CKB-initialized repository.

Remove Repository

ckb federation remove <federation> <repo-id>

Removes a repository from the federation.

Rename Repository

ckb federation rename <federation> <old-id> <new-id>

Changes a repository's alias. The UUID remains unchanged.

List Repositories

ckb federation repos <name> [--json]

Lists all repositories in a federation with their paths, tags, and add dates.

Sync Federation

ckb federation sync <name> [--force] [--dry-run] [--json]

Syncs repository data to the federation index:

--force - Sync even if data appears fresh
--dry-run - Preview what would be synced
--json - Output results as JSON

Search Modules

ckb federation search-modules <federation> [--query=<query>] [--repos=<id1,id2>] [--tags=<tag1,tag2>] [--limit=50] [--json]

Search for modules across all repositories in the federation.

# Find all authentication modules
ckb federation search-modules platform --query=auth

# Search within specific repos
ckb federation search-modules platform --query=handler --repos=api,web

# Filter by tags
ckb federation search-modules platform --tags=core,infrastructure

Search Ownership

ckb federation search-ownership <federation> [--path=<glob>] [--repos=<id1,id2>] [--limit=50] [--json]

Search for ownership patterns across all repositories.

# Find all API ownership
ckb federation search-ownership platform --path="**/api/**"

# Search within specific repos
ckb federation search-ownership platform --repos=api,auth

Get Hotspots

ckb federation hotspots <federation> [--top=20] [--min-score=0.3] [--repos=<id1,id2>] [--json]

Returns merged hotspots (high churn + complexity) across all repositories.

# Top 20 hotspots (default)
ckb federation hotspots platform

# Top 50 with higher threshold
ckb federation hotspots platform --top=50 --min-score=0.5

# Filter to specific repos
ckb federation hotspots platform --repos=api,auth

Search Decisions

ckb federation search-decisions <federation> [--query=<query>] [--module=<module>] [--status=<status1,status2>] [--repos=<id1,id2>] [--limit=50] [--json]

Search for architectural decisions (ADRs) across all repositories.

# Find all database decisions
ckb federation search-decisions platform --query=database

# Filter by status
ckb federation search-decisions platform --status=accepted,proposed

# Filter by affected module
ckb federation search-decisions platform --module=internal/api

HTTP API

List Federations

GET /federations

Returns all available federations.

curl http://localhost:8080/federations

{
  "federations": ["platform", "infrastructure"],
  "count": 2
}

Federation Status

GET /federations/:name/status

Returns detailed federation status.

curl http://localhost:8080/federations/platform/status

{
  "name": "platform",
  "description": "Our microservices platform",
  "createdAt": "2024-12-18T10:00:00Z",
  "repoCount": 4,
  "repos": [...],
  "compatibility": {
    "compatible": 3,
    "incompatible": 1
  }
}

List Repositories

GET /federations/:name/repos[?includeCompatibility=true]

Returns repositories in the federation.

curl http://localhost:8080/federations/platform/repos?includeCompatibility=true

Search Modules

GET /federations/:name/modules?q=<query>&repos=<id1,id2>&tags=<tag1,tag2>&limit=50

Search for modules across all repositories.

# Find all authentication modules
curl "http://localhost:8080/federations/platform/modules?q=auth"

# Search within specific repos
curl "http://localhost:8080/federations/platform/modules?q=handler&repos=api,web"

Response includes staleness information:

{
  "modules": [
    {
      "repoId": "api",
      "moduleId": "internal/auth",
      "name": "auth",
      "responsibility": "User authentication and session management",
      "ownerRef": "@security-team"
    }
  ],
  "total": 1,
  "staleness": {
    "overallStaleness": "fresh",
    "refreshRecommended": false
  }
}

Search Ownership

GET /federations/:name/ownership?path=<glob>&repos=<id1,id2>&limit=50

Search for ownership patterns across repositories.

# Find all API ownership
curl "http://localhost:8080/federations/platform/ownership?path=**/api/**"

Get Hotspots

GET /federations/:name/hotspots?repos=<id1,id2>&top=20&minScore=0.3

Returns merged hotspots across all repositories.

curl "http://localhost:8080/federations/platform/hotspots?top=10"

Search Decisions

GET /federations/:name/decisions?q=<query>&status=accepted&repos=<id1,id2>&module=<module>&limit=50

Search for architectural decisions (ADRs) across repositories.

# Find all accepted authentication decisions
curl "http://localhost:8080/federations/platform/decisions?q=authentication&status=accepted"

Sync Federation

POST /federations/:name/sync
Content-Type: application/json

{
  "force": false,
  "dryRun": false,
  "repoIds": ["api", "auth"]  // optional, default: all
}

Syncs repository data to the federation index.

curl -X POST http://localhost:8080/federations/platform/sync \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

MCP Tools

Federation adds 8 new MCP tools for AI assistant integration.

listFederations

List all available federations.

{
  "name": "listFederations",
  "arguments": {}
}

federationStatus

Get detailed status of a federation.

{
  "name": "federationStatus",
  "arguments": {
    "federation": "platform"
  }
}

federationRepos

List repositories in a federation.

{
  "name": "federationRepos",
  "arguments": {
    "federation": "platform",
    "includeCompatibility": true
  }
}

federationSearchModules

Search for modules across all repositories.

{
  "name": "federationSearchModules",
  "arguments": {
    "federation": "platform",
    "query": "authentication",
    "repos": ["api", "auth"],
    "limit": 20
  }
}

federationSearchOwnership

Search for ownership patterns across repositories.

{
  "name": "federationSearchOwnership",
  "arguments": {
    "federation": "platform",
    "path": "**/api/**",
    "limit": 50
  }
}

federationGetHotspots

Get merged hotspots across all repositories.

{
  "name": "federationGetHotspots",
  "arguments": {
    "federation": "platform",
    "top": 20,
    "minScore": 0.3
  }
}

federationSearchDecisions

Search for architectural decisions across repositories.

{
  "name": "federationSearchDecisions",
  "arguments": {
    "federation": "platform",
    "query": "database",
    "status": ["accepted"],
    "module": "persistence"
  }
}

federationSync

Sync federation index from repository data.

{
  "name": "federationSync",
  "arguments": {
    "federation": "platform",
    "force": true,
    "dryRun": false,
    "repos": ["api"]
  }
}

Configuration

Federation data is stored in ~/.ckb/federation/<name>/:

~/.ckb/federation/
└── platform/
    ├── config.toml    # Federation configuration
    └── index.db       # SQLite index database

config.toml Format

name = "platform"
description = "Our microservices platform"
created_at = "2024-12-18T10:00:00Z"
updated_at = "2024-12-18T14:30:00Z"

[[repos]]
repo_uid = "550e8400-e29b-41d4-a716-446655440001"
repo_id = "api"
path = "/code/api-service"
tags = ["backend", "core"]
added_at = "2024-12-18T10:05:00Z"

[[repos]]
repo_uid = "550e8400-e29b-41d4-a716-446655440002"
repo_id = "auth"
path = "/code/auth-service"
tags = ["backend", "security"]
added_at = "2024-12-18T10:06:00Z"

Use Cases

Cross-Repo Module Search

Find all "authentication" modules across your organization:

# CLI
ckb federation sync platform
# Then use HTTP/MCP to search

# HTTP
curl "http://localhost:8080/federations/platform/modules?q=auth"

Organization-Wide Hotspots

Identify the most volatile code across all services:

curl "http://localhost:8080/federations/platform/hotspots?top=20"

Unified Ownership View

Find who owns API code across the organization:

curl "http://localhost:8080/federations/platform/ownership?path=**/api/**"

Cross-Repo Decision Search

Find all decisions related to databases:

curl "http://localhost:8080/federations/platform/decisions?q=database&status=accepted"

PR Review Across Repos

When reviewing changes that span multiple repositories:

User: "Who should review changes to the auth system?"

AI (using federationSearchOwnership):
Based on the federation data:
- api-service: @security-team, @api-team
- auth-service: @security-team (primary), @platform-team
- web-app: @frontend-team (for auth UI)

Recommended reviewers: @security-team (owns auth across all repos)

Best Practices

1. Keep Repos Synced

Run sync regularly or after significant changes:

# In CI/CD after deployment
ckb federation sync platform

2. Use Tags for Filtering

Tag repositories by domain for focused queries:

ckb federation add platform --repo-id=api --path=/code/api --tags=backend,core
ckb federation add platform --repo-id=web --path=/code/web --tags=frontend

Then filter:

curl "http://localhost:8080/federations/platform/modules?tags=backend"

3. Handle Staleness

Always check staleness in query results:

result = query_federation_modules("platform", "auth")
if result["staleness"]["refreshRecommended"]:
    sync_federation("platform")
    result = query_federation_modules("platform", "auth")

4. Monitor Compatibility

Before critical operations, verify all repos are compatible:

ckb federation status platform
# Ensure Compatible: N/N

5. Name Repos Meaningfully

Use consistent, descriptive repo IDs:

# Good
--repo-id=user-api
--repo-id=payment-service
--repo-id=admin-dashboard

# Avoid
--repo-id=repo1
--repo-id=backend
--repo-id=new

Troubleshooting

Repo Shows as Incompatible

Warning: Schema version 2 is below minimum 6
Action: Run: cd /path/to/repo && ckb refresh --migrate

Run the suggested command to upgrade the schema.

Sync Skipped

REPO ID  STATUS   MODULES  OWNERSHIP  HOTSPOTS  DECISIONS  DURATION
api      skipped  0        0          0         0          0ms

Check repo compatibility:

ckb federation repos platform --json | jq '.compatibility'

Federation Not Found

Error: federation "platform" not found

List available federations:

ckb federation list

Path Does Not Exist

Error: path does not exist: /code/old-location

Update the repo path or remove and re-add:

ckb federation remove platform old-api
ckb federation add platform --repo-id=api --path=/code/new-location

Limitations

Local only - Federation currently works with local filesystem paths only
Schema v6+ - Requires all repos to have CKB schema version 6 or higher
Manual sync - Index must be explicitly synced (no automatic watching)
Top 20 hotspots - Only top 20 hotspots per repo are indexed

Contract-Aware Impact Analysis (v6.3)

v6.3 adds contract detection and cross-repo dependency tracking through explicit API boundaries. This enables answering questions like "What breaks if I change this shared API?"

Supported Contract Types

Type	Extensions	Detection
proto	`.proto`	Package, imports, services, messages
openapi	`.yaml`, `.json` (with openapi/swagger key)	Version, paths, servers

Visibility Classification

Contracts are classified by visibility:

Visibility	Criteria
public	Under `api/`, `proto/`, versioned package (`v1`, `v2`), or has service definitions
internal	Under `internal/`, `testdata/`, or package name contains "internal"
unknown	No clear signals (treated conservatively as public)

Evidence Tiers

Contract dependency edges have confidence tiers:

Tier	Confidence	Source
Declared (tier 1)	1.0	`buf.yaml` deps, proto imports, generated code (`.pb.go`, `.pb.ts`)
Derived (tier 2)	0.7-0.9	Type-matching heuristics, same package references
Heuristic (tier 3)	≤0.5	File naming patterns (hidden by default)

Contract CLI Commands

List Contracts

# List all contracts in a federation
ckb contracts list platform

# Filter by repo
ckb contracts list platform --repo=api

# Filter by type
ckb contracts list platform --type=proto

# Filter by visibility
ckb contracts list platform --visibility=public

# JSON output
ckb contracts list platform --json

Analyze Contract Impact

# Analyze impact of changing a contract
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto

# Include transitive consumers
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto --include-transitive

# Include heuristic (tier 3) edges
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto --include-heuristic

# Set max depth for transitive analysis
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto --max-depth=5

Output includes:

Contract info - Type, visibility, path
Direct consumers - Repos that import/use the contract with evidence tier
Transitive consumers - Repos reached through contract imports (with depth)
Risk assessment - low/medium/high with risk factors
Ownership - Who to contact for approval

Get Contract Dependencies

# Show what contracts a repo depends on
ckb contracts deps platform --repo=api --direction=dependencies

# Show what repos consume contracts from this repo
ckb contracts deps platform --repo=api --direction=consumers

# Show both directions (default)
ckb contracts deps platform --repo=api --direction=both

Manage Edges

# Suppress a false positive edge
ckb contracts suppress platform --edge=123 --reason="Not actually used"

# Verify an edge (increase confidence)
ckb contracts verify platform --edge=123

Contract Statistics

# Show contract statistics for a federation
ckb contracts stats platform

Output:

Contract Statistics:
  Total contracts:    45
    Public:           32
    Internal:         13

By type:
  proto        38
  openapi       7

Dependency edges:
  Total:              123
    Declared (tier 1): 89
    Derived (tier 2):  34

Risk Assessment

Impact analysis computes risk based on:

Factor	Risk Impact
Direct consumers > 5	High
Direct consumers > 2	Medium
Transitive consumers present	+1 level
Public visibility	+1 level
Has service definitions	+1 level
Versioned (v1, v2)	Indicates stable API

MCP Contract Tools

See MCP Integration for the 6 new contract tools:

listContracts - List contracts in a federation
analyzeContractImpact - Analyze impact of changing a contract
getContractDependencies - Get contract dependencies for a repo
suppressContractEdge - Suppress false positive edges
verifyContractEdge - Verify an edge
getContractStats - Get contract statistics

Workflow: Before Changing a Shared API

# 1. Find the contract
ckb contracts list platform --repo=api --type=proto

# 2. Analyze impact
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto

# 3. Contact owners listed in output

# 4. Make change and re-sync
ckb federation sync platform

Proto Import Graph

For protobuf contracts, CKB builds an import graph that enables transitive consumer detection:

api-service/proto/user.proto
    ↓ imported by
gateway/proto/gateway.proto
    ↓ imported by
web-app/generated/api.ts

When user.proto changes, both gateway and web-app are identified as affected.

Related: Runtime Telemetry (v6.4)

v6.4 adds runtime telemetry integration for observed usage analysis. While not federation-specific, telemetry data can enhance contract impact analysis by showing which contracts are actually called at runtime. See Configuration for telemetry setup.

Remote Index Serving (v7.3)

v7.3 adds remote index serving — the first phase of v3 Federation. This enables serving symbol indexes over HTTP so remote clients can query code intelligence without direct database access.

Enabling Remote Index Mode

# Start server with index-serving endpoints
ckb serve --index-server --index-config /path/to/config.toml

Configuration (TOML)

Create a configuration file for the index server:

[index_server]
enabled = true
max_page_size = 10000

[[repos]]
id = "company/core-lib"
name = "Core Library"
path = "/repos/core-lib"
description = "Shared utilities and common code"

[[repos]]
id = "company/api"
name = "API Service"
path = "/repos/api"

[repos.privacy]
expose_paths = true
expose_docs = false
expose_signatures = false
path_prefix_strip = "/home/build/"

[default_privacy]
expose_paths = true
expose_docs = true
expose_signatures = true

REST API Endpoints

Endpoint	Description
`GET /index/repos`	List all indexed repositories
`GET /index/repos/{repo}/meta`	Repository metadata and capabilities
`GET /index/repos/{repo}/files`	List files with cursor pagination
`GET /index/repos/{repo}/symbols`	List symbols with filtering
`GET /index/repos/{repo}/symbols/{id}`	Get single symbol by ID
`POST /index/repos/{repo}/symbols:batchGet`	Batch get multiple symbols
`GET /index/repos/{repo}/refs`	List references with pagination
`GET /index/repos/{repo}/callgraph`	List call graph edges
`GET /index/repos/{repo}/search/symbols`	Search symbols by name
`GET /index/repos/{repo}/search/files`	Search files by path

Security Features

HMAC-Signed Cursors — Pagination cursors are cryptographically signed to prevent tampering
Privacy Redaction — Per-repo controls for exposing file paths, documentation, and signatures
Path Prefix Stripping — Remove sensitive path prefixes (e.g., /home/build/) from responses
Read-Only Mode — Index server opens databases in read-only mode for safety

Use Cases

Centralized Code Intelligence Server: Run a single CKB instance that serves indexes for multiple repositories, allowing AI tools and IDEs to query code intelligence without local SCIP indexes.

Cross-Team Symbol Lookup: Teams can query symbols from other repositories without needing direct access to those codebases.

Federation Client Foundation: Remote index serving is Phase 1 of v3 Federation. Future phases will add incremental sync, change journals, and full federation client support.

See API Reference for complete endpoint documentation with examples.

Index Upload (v7.3 Phase 2)

v7.3 also adds index upload capability — Phase 2 of v3 Federation. This enables pushing SCIP indexes to the server via HTTP, eliminating the need for local filesystem paths. CKB transforms from a "bring your database" model to a centralized index hosting service.

Upload Configuration

[index_server]
enabled = true
data_dir = "~/.ckb-server"      # Server data directory
max_upload_size = 524288000     # 500MB default
allow_create_repo = true        # Allow repo creation via API

Data Directory Structure

~/.ckb-server/
├── repos/
│   └── company-core-lib/
│       ├── ckb.db        # SQLite database
│       └── meta.json     # Repo metadata (name, description, timestamps)
└── uploads/              # Temp directory for in-progress uploads

REST API Endpoints

Endpoint	Method	Description
`/index/repos`	POST	Create a new repo ready for upload
`/index/repos/{repo}/upload`	POST	Upload SCIP index file (supports gzip, zstd compression)
`/index/repos/{repo}/upload/delta`	POST	Delta upload - only changed files (Phase 3)
`/index/repos/{repo}`	DELETE	Delete an uploaded repo

Creating a Repo

curl -X POST http://localhost:8080/index/repos \
  -H "Content-Type: application/json" \
  -d '{
    "id": "company/core-lib",
    "name": "Core Library",
    "description": "Shared utilities"
  }'

Response:

{
  "data": {
    "id": "company/core-lib",
    "name": "Core Library",
    "status": "created"
  }
}

Uploading an Index

# Generate SCIP index locally
scip-go

# Upload to server
curl -X POST http://localhost:8080/index/repos/company/core-lib/upload \
  -H "Content-Type: application/octet-stream" \
  -H "X-CKB-Commit: abc123" \
  -H "X-CKB-Language: go" \
  --data-binary @index.scip

Response:

{
  "data": {
    "repo_id": "company/core-lib",
    "commit": "abc123",
    "languages": ["go"],
    "stats": {
      "files": 150,
      "symbols": 3200,
      "refs": 15000,
      "call_edges": 8500
    },
    "duration_ms": 2340
  }
}

Upload Metadata Headers

Header	Description
`X-CKB-Commit`	Git commit hash (optional, auto-detected from SCIP)
`X-CKB-Language`	Primary language (optional, auto-detected)
`X-CKB-Indexer-Name`	Indexer name (e.g., "scip-go")
`X-CKB-Indexer-Version`	Indexer version

Auto-Create on Upload

If allow_create_repo = true, repos are automatically created on first upload:

# Repo doesn't exist yet - will be created automatically
curl -X POST http://localhost:8080/index/repos/new-repo/upload \
  -H "Content-Type: application/octet-stream" \
  --data-binary @index.scip

Deleting a Repo

curl -X DELETE http://localhost:8080/index/repos/company/core-lib

Response:

{
  "data": {
    "id": "company/core-lib",
    "status": "deleted"
  }
}

Note: Only uploaded repos can be deleted via API. Config-based repos cannot be deleted.

Authentication & API Keys (v7.4 Phase 4)

v7.4 adds scoped API key authentication for the index server, enabling secure multi-tenant access with fine-grained permissions.

Scopes

Scope	Permissions
read	GET requests, symbol lookup, search
write	POST requests, upload indexes, create repos
admin	Full access including token management and deletions

Scopes are hierarchical: admin includes write, which includes read.

Token Management CLI

# Create a new token
ckb token create --name "CI Upload" --scopes write
ckb token create --name "Read-only" --scopes read --repos "myorg/*"
ckb token create --name "Admin" --scopes admin --expires 30d

# List all tokens
ckb token list
ckb token list --show-revoked

# Revoke a token
ckb token revoke ckb_key_abc123

# Rotate a token (new secret, same ID)
ckb token rotate ckb_key_abc123

Token Format

Token: ckb_sk_ prefix + 64 hex chars (shown once at creation)
Key ID: ckb_key_ prefix + 16 hex chars (used for management)

Tokens are bcrypt hashed before storage — only the prefix is visible in token list.

Configuration

[index_server.auth]
enabled = true
require_auth = true                    # false = unauthenticated gets read-only
legacy_token = "${CKB_LEGACY_TOKEN}"   # Backward compatibility

# Static keys (defined in config, useful for CI)
[[index_server.auth.static_keys]]
id = "ci-upload"
name = "CI Upload Key"
token = "${CI_CKB_TOKEN}"              # Supports env var expansion
scopes = ["write"]
repo_patterns = ["myorg/*"]            # Restrict to matching repos
rate_limit = 100

[index_server.auth.rate_limiting]
enabled = true
default_limit = 60                     # Requests per minute
burst_size = 10

Per-Repo Restrictions

Keys can be restricted to specific repositories using glob patterns:

# Create a key that only works for myorg/* repos
ckb token create --name "MyOrg CI" --scopes write --repos "myorg/*"

Pattern syntax:

* — Match all repos
myorg/* — Match all repos starting with myorg/
myorg/api — Match exact repo ID

Rate Limiting

When enabled, rate limiting uses a token bucket algorithm:

[index_server.auth.rate_limiting]
enabled = true
default_limit = 60    # Tokens per minute
burst_size = 10       # Initial bucket size

When rate limited, the server responds with:

429 Too Many Requests
Retry-After: <seconds> header
X-RateLimit-Remaining: 0 header

HTTP Authentication

Use the Authorization header with Bearer token:

# Upload with authentication
curl -X POST http://localhost:8080/index/repos/myorg/api/upload \
  -H "Authorization: Bearer ckb_sk_9f8e7d6c5b4a3928_1a2b3c4d5e6f..." \
  -H "Content-Type: application/octet-stream" \
  --data-binary @index.scip

Error Responses

Status	Error Code	Meaning
401	`missing_token`	No Authorization header
401	`invalid_token`	Token not found
401	`expired_token`	Token past expiration
401	`revoked_token`	Token was revoked
403	`insufficient_scope`	Token lacks required scope
403	`repo_not_allowed`	Token can't access this repo
429	`rate_limited`	Too many requests

Error response format:

{
  "error": {
    "code": "insufficient_scope",
    "message": "token requires 'write' scope for this operation"
  }
}

Backward Compatibility

Legacy Token Mode: If you were using the simple token config before, you can migrate by setting legacy_token:

[index_server.auth]
enabled = true
legacy_token = "${OLD_TOKEN}"   # Old token still works

The legacy token has full admin access.

Unauthenticated Access: When require_auth = false, unauthenticated requests get read-only access. This is useful for public indexes where you want anyone to query but restrict uploads.

Use Cases

CI/CD Index Publishing:

# Create a write-only token for CI
ckb token create --name "CI" --scopes write --repos "myorg/*"

# In CI pipeline
curl -X POST http://codeserver.internal/index/repos/$REPO_ID/upload \
  -H "Authorization: Bearer $CKB_CI_TOKEN" \
  -H "X-CKB-Commit: $GIT_SHA" \
  --data-binary @index.scip

Multi-Tenant Server:

# Create restricted keys for each team
ckb token create --name "Team A" --scopes write --repos "team-a/*"
ckb token create --name "Team B" --scopes write --repos "team-b/*"

Read-Only API Access:

# Token for querying only
ckb token create --name "Dashboard" --scopes read --rate-limit 120

Air-Gapped Environments: Generate SCIP indexes in restricted environments and upload to a central server via HTTP.

Future

Team dashboards
Automatic sync triggers
GraphQL contract support
AsyncAPI contract support
Telemetry aggregation across federation
Federation v3 Phase 5: Full federation client with remote sync

Uh oh!

Uh oh!

Federation

Federation (v6.3)

What is Federation?

Quick Start

Core Concepts

Repository Identity

Federation Index

Schema Compatibility

Staleness Propagation

CLI Commands

Create a Federation

Delete a Federation

List Federations

Federation Status

Add Repository

Remove Repository

Rename Repository

List Repositories

Sync Federation

Search Modules

Search Ownership

Get Hotspots

Search Decisions

HTTP API

List Federations

Federation Status

List Repositories

Search Modules

Search Ownership

Get Hotspots

Search Decisions

Sync Federation

MCP Tools

listFederations

federationStatus

federationRepos

federationSearchModules

federationSearchOwnership

federationGetHotspots

federationSearchDecisions

federationSync

Configuration

config.toml Format

Use Cases

Cross-Repo Module Search

Organization-Wide Hotspots

Unified Ownership View

Cross-Repo Decision Search

PR Review Across Repos

Best Practices

1. Keep Repos Synced

2. Use Tags for Filtering

3. Handle Staleness

4. Monitor Compatibility

5. Name Repos Meaningfully

Troubleshooting

Repo Shows as Incompatible

Sync Skipped

Federation Not Found

Path Does Not Exist

Limitations

Contract-Aware Impact Analysis (v6.3)

Supported Contract Types

Visibility Classification

Evidence Tiers

Contract CLI Commands

List Contracts

Analyze Contract Impact

Get Contract Dependencies

Manage Edges

Contract Statistics

Risk Assessment

MCP Contract Tools

Workflow: Before Changing a Shared API

Proto Import Graph

Related: Runtime Telemetry (v6.4)

Remote Index Serving (v7.3)

Enabling Remote Index Mode