Skip to main content

​
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: "text-embedding-004"

defaults:
  similarity_threshold: 0.70
  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.70
  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.70
  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.70
  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