Skip to content

configuration.md

Latest commit

 

History

History
214 lines (171 loc) · 6.65 KB

configuration.md

File metadata and controls

214 lines (171 loc) · 6.65 KB

Configuration

Environment Variables (.env)

Variable Required Default Description
GITLAB_URL Yes -- GitLab instance URL
GITLAB_TOKEN Yes -- Bot Personal Access Token (api scope)
GITLAB_WEBHOOK_SECRET Yes -- Webhook validation secret
CODEWARD_BOT_USERNAME No codeward-bot Bot's GitLab username
DATABASE_URL No sqlite+aiosqlite:///./data/codeward.db Database connection URL. Postgres is recommended for anything beyond a quick trial: postgresql+asyncpg://user:pass@host:5432/codeward.
LITELLM_URL No http://litellm:4000 LiteLLM proxy URL. Use http://localhost:4000 when running Codeward locally with make run.
REDIS_URL No -- Redis URL. Required for the multi-agent flow runner and the make worker process; optional otherwise. Example: redis://localhost:6379/0.
CODEWARD_AGENTS_DIR No agents Directory containing agent YAML definitions.
CODEWARD_MENTION_PATTERN No @codeward Mention trigger pattern
CODEWARD_MCP_KEY No -- Bearer token required to call the /mcp mount. If unset, the MCP server is exposed without authentication. See MCP.
LOG_LEVEL No INFO Logging level (DEBUG, INFO, WARNING, ERROR)
AGNO_TELEMETRY No false Agno framework telemetry toggle

Configuration (codeward.yml)

The codeward.yml file provides additional configuration. See codeward.example.yml for the full schema.

Models

codeward:
  models:
    fast: fast           # Quick, low-cost tasks
    default: strong      # General purpose
    strong: strong       # Complex reasoning
    code: code           # Code-focused tasks

Each model alias maps to a model defined in litellm-config.yaml.

Defaults

codeward:
  defaults:
    auto_review: true
    auto_pipeline_debug: true
    auto_security_triage: false
    mention_trigger: "@codeward"
    cooldown_seconds: 120
    max_diff_lines: 2000
    skip_draft_mrs: true

Labels

codeward:
  labels:
    reviewed: ai-reviewed
    needs_changes: ai-needs-changes
    security_critical: security-critical

Rate Limits

codeward:
  rate_limits:
    per_project_per_hour: 30
    per_user_per_hour: 20
    global_per_minute: 10

Token Budgets

codeward:
  token_budgets:
    total: 24000
    diff: 12000
    per_file_diff: 4000
    pipeline_logs: 3000
    description: 2000
    previous_reviews: 3000

External MCP Servers (codeward.mcp_servers)

Declares the external Model Context Protocol servers that agents can draw tools from. Each entry's key is the server name referenced from the agent YAML's mcp_servers: list. The full schema lives in codeward/mcp_client/registry.py (MCPServerConfig); see MCP and AGENTS.md for the agent-side wiring.

codeward:
  mcp_servers:
    context7:
      url: https://mcp.context7.com/mcp
      transport: streamable-http       # streamable-http | sse
      auth_type: bearer                # bearer | header | none
      auth_token_env: CONTEXT7_TOKEN
      enabled: true
      description: Context7 documentation lookups

    internal-kb:
      url: https://kb.internal/mcp
      transport: streamable-http
      auth_type: header
      headers:
        X-API-Key: ${INTERNAL_KB_KEY}  # ${VAR} expansion is supported

Redaction

codeward:
  redaction:
    entropy_threshold: 4.5    # Strings with higher entropy are redacted
    extra_patterns: []         # Additional regex patterns to redact

Precedence

Environment variables > .env file > codeward.yml defaults.

LiteLLM Configuration (litellm-config.yaml)

Defines model routing for the LiteLLM proxy. See litellm-config.example.yaml for the shipped defaults.

model_list:
  # Fast tier — quick, low-cost reasoning. Used for triage, mention
  # parsing, short chat replies, and any agent step that doesn't need
  # a frontier model.
  - model_name: fast
    litellm_params:
      model: openai/gpt-4.1-mini
      api_key: os.environ/OPENAI_API_KEY
      max_tokens: 4096

  # Strong tier — complex reasoning, full code reviews, security triage.
  - model_name: strong
    litellm_params:
      model: openrouter/anthropic/claude-sonnet-4
      api_key: os.environ/OPENROUTER_API_KEY
      max_tokens: 8192

  # Code tier — code-focused tasks (diff review, code generation in flows).
  # Qwen3.5-35B-A3B is a Mixture-of-Experts coder model on OpenRouter.
  - model_name: code
    litellm_params:
      model: openrouter/qwen/qwen3.5-35b-a3b
      api_key: os.environ/OPENROUTER_API_KEY
      max_tokens: 8192

The model_name on each entry is the tier alias agents reference from codeward.yml (models.fast, models.strong, models.code). To swap in a different provider, change the litellm_params.model value and make sure the corresponding API key env var is set in .env.

Required environment variables for the defaults above:

OPENAI_API_KEY=sk-...           # for fast (gpt-4.1-mini)
OPENROUTER_API_KEY=sk-or-v1-... # for strong (Claude Sonnet 4) and code (Qwen3.5-35B-A3B)

Swapping in alternative providers

A few common substitutions for the fast and code tiers:

# fast — local Ollama (zero API cost, requires Ollama running on the host)
- model_name: fast
  litellm_params:
    model: ollama/llama3.1:8b
    api_base: http://host.docker.internal:11434

# fast — Anthropic Haiku
- model_name: fast
  litellm_params:
    model: anthropic/claude-haiku-4-5
    api_key: os.environ/ANTHROPIC_API_KEY

# code — DeepSeek Coder via OpenRouter
- model_name: code
  litellm_params:
    model: openrouter/deepseek/deepseek-coder-v3
    api_key: os.environ/OPENROUTER_API_KEY

Docker Compose Options

Profile Services Started Use Case
(default) redis, litellm, litellm-db Local development — Codeward and the worker run on the host via uv / make run / make worker
full Everything above plus codeward and codeward-worker (×2 replicas) Production-style deployment where the app also runs in Docker 
# Development (codeward + worker run locally via make)
docker compose up -d

# Full deployment
docker compose --profile full up -d

Note that the litellm-db Postgres in docker-compose.yml is dedicated to LiteLLM. Codeward's own database is configured separately via DATABASE_URL (see the env var table above).

Project Configuration (.codeward.yml)

Per-project overrides placed in the repository root. See Usage for details.