Configuration Inheritance

Share configurations across projects

Configuration Inheritance

Use configuration inheritance to share settings across projects while allowing per-project customization.

Overview

Without Inheritance (Duplicate Config):

backend/simili.yaml    - Full config copy
frontend/simili.yaml   - Same config copy
mobile/simili.yaml     - Same config copy

With Inheritance (DRY):

base-config.yaml  - Shared configuration
  ├─ backend/simili.yaml     - Extends base, adds specific settings
  ├─ frontend/simili.yaml    - Extends base, adds specific settings
  └─ mobile/simili.yaml      - Extends base, adds specific settings

How it works

1. Parent Config - Stored in shared repository
2. Child Config - References parent via extends
3. Fetch & Merge - Child fetches parent, merges settings
4. Override - Child settings override parent

Setup

1. Create base configuration

In company/policies repository:

# simili-base.yaml
qdrant:
  url: "${QDRANT_URL}"
  api_key: "${QDRANT_API_KEY}"
  collection: "organization-issues"

embedding:
  provider: "gemini"
  api_key: "${GEMINI_API_KEY}"
  model: "gemini-embedding-001"

defaults:
  similarity_threshold: 0.65
  max_similar_to_show: 5
  cross_repo_search: true

transfer:
  enabled: true
  llm_routing_enabled: true
  rules:
    - name: "Route documentation"
      priority: 100
      target: "company/docs"
      title_contains: ["documentation", "docs"]

2. Create child configurations

In individual repositories:

backend/.github/simili.yaml:

extends: "https://raw.githubusercontent.com/company/policies/main/simili-base.yaml"

repositories:
  - org: "company"
    repo: "backend"
    enabled: true
    description: "REST APIs and microservices"

frontend/.github/simili.yaml:

extends: "https://raw.githubusercontent.com/company/policies/main/simili-base.yaml"

repositories:
  - org: "company"
    repo: "frontend"
    enabled: true
    description: "React web application"

Merging rules

When child extends parent:

1. Parent loaded and parsed
2. Child loaded and parsed
3. Child values override parent
4. Arrays are replaced (not merged)

Example:

# Parent
defaults:
  similarity_threshold: 0.65
  max_similar_to_show: 5

# Child
extends: "..."
defaults:
  similarity_threshold: 0.75  # Overrides

# Result
defaults:
  similarity_threshold: 0.75  # From child
  max_similar_to_show: 5      # From parent

Use cases

Organization-wide defaults

Parent handles organization policies:

# Organization standards for all repos
defaults:
  similarity_threshold: 0.65
  cross_repo_search: true

transfer:
  enabled: true
  llm_routing_enabled: true

Child customizes per repository:

# Team-specific repositories
repositories:
  - org: "company"
    repo: "backend"
    description: "Backend for our team"

Multiple inheritance levels

# base.yaml (organization)
qdrant: {...}
embedding: {...}

# team-config.yaml extends base.yaml
extends: "https://...base.yaml"
defaults:
  cross_repo_search: false  # Team-specific

# backend.yaml extends team-config.yaml
extends: "https://...team-config.yaml"
repositories:
  - org: "company"
    repo: "backend-service"

Three levels:

1. Organization defaults
2. Team customizations
3. Repository specifics

Staged rollouts

Base (stable):

transfer:
  llm_routing_enabled: false

Staging (testing):

extends: "https://...base.yaml"
transfer:
  llm_routing_enabled: true  # Test new feature

Production (when stable): Update base.yaml, all inherit

Best practices

1. Keep base minimal

Base should have:

• Common credentials setup
• Organization-wide policies
• Standard library versions

Avoid:

• Repository-specific rules
• Per-team exceptions
• Implementation details

2. Use raw GitHub URLs

Always use raw content URLs:

extends: "https://raw.githubusercontent.com/company/policies/main/simili.yaml"

Not:

extends: "https://github.com/company/policies/blob/main/simili.yaml"

3. Version your configs

Tag base configurations:

extends: "https://raw.githubusercontent.com/company/policies/v1.0/simili.yaml"

Allows:

• Safe updates to old configs
• Gradual migration to new versions
• A/B testing configurations

4. Document inheritance

Add comments in child config:

# Extends organization base configuration (v1.0)
# Overrides: repositories, transfer rules
extends: "https://raw.githubusercontent.com/company/policies/v1.0/simili.yaml"

# Repository-specific configuration
repositories:
  - org: "company"
    repo: "my-service"

Troubleshooting

Configuration not found

Error: Failed to fetch extends URL

Solutions:

• Verify URL is correct and accessible
• Check GitHub repository is public
• Use raw content URL, not web UI URL
• Verify base configuration file exists

Merge conflicts

Issue: Child and parent have incompatible settings

Solution: Explicitly override in child

extends: "..."
# Parent might have rules that conflict
# Override here
transfer:
  rules:
    - name: "Team-specific rule"
      priority: 100  # Higher than parent
      target: "company/team-repo"

Circular dependencies

Error: Config extends itself (directly or indirectly)

Solution: Check inheritance chain

A extends B
B extends A  # Don't do this!

Performance

Fetch time

• First fetch: 100-500ms (network)
• Cached: <10ms
• No real-world impact on processing

Size limits

• No hard limit on config size
• Typical: <10KB
• Can handle 100+ repositories

Migration path

Step 1: Create Base

• Extract common config to repository
• Store in company/policies

Step 2: Add extends

• Update individual repos to extend base
• Keep all settings same (no breaking changes)

Step 3: Remove Duplication

• Move common parts to base
• Keep only repo-specific in child

Step 4: Maintain Centrally

• Update base when needed
• All repos automatically use new config
• Gradual rollout possible with versions

Real-world example

# company/policies/.github/simili-base.yaml
qdrant:
  url: "${QDRANT_URL}"
  api_key: "${QDRANT_API_KEY}"
  collection: "company-issues"

embedding:
  provider: "gemini"
  api_key: "${GEMINI_API_KEY}"

defaults:
  similarity_threshold: 0.65
  max_similar_to_show: 5
  cross_repo_search: true

transfer:
  enabled: true
  llm_routing_enabled: true

# backend/.github/simili.yaml
extends: "https://raw.githubusercontent.com/company/policies/main/.github/simili-base.yaml"

repositories:
  - org: "company"
    repo: "backend"
    description: "REST APIs"

transfer:
  rules:
    - name: "Backend specific rule"
      priority: 10
      target: "company/backend"
      labels: ["backend"]

Easy to update organization-wide settings while keeping repo-specific rules!

Next steps

Patterns overview

Manage multiple repositories

Configuration overview

View all configuration options