.env.example

# Forge SDLC Orchestrator - Environment Variables
# Copy this file to .env and fill in the values

# =============================================================================
# Redis Configuration
# =============================================================================
# Requires Redis Stack (not standard Redis) for RediSearch module
# Start with: podman run -d --name redis-stack -p 6380:6379 redis/redis-stack-server:latest
# Use port 6380 to avoid conflicts with other Redis instances (e.g., Langfuse)
REDIS_URL=redis://localhost:6380/0

# =============================================================================
# Jira Configuration
# =============================================================================
JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_API_TOKEN=your-jira-api-token
JIRA_USER_EMAIL=your-email@company.com
JIRA_WEBHOOK_SECRET=your-jira-webhook-secret
# Jira domain for MCP tools (derived from JIRA_BASE_URL if not set)
# JIRA_DOMAIN=your-company.atlassian.net
# Custom field ID for Specification (find in Jira admin, optional)
# JIRA_SPEC_CUSTOM_FIELD=customfield_10050

# Flexible Jira Configuration
# Set these to true if your Jira project doesn't have custom statuses/fields
# When true, Forge will use labels to track workflow state instead of status transitions
JIRA_USE_LABELS=true
# When true, PRD/Spec content is stored in structured comments instead of custom fields
JIRA_STORE_IN_COMMENTS=true

# =============================================================================
# GitHub Configuration
# =============================================================================
GITHUB_TOKEN=your-github-personal-access-token
GITHUB_WEBHOOK_SECRET=your-github-webhook-secret
# GitHub account/org where forks are created (leave empty to fork as the authenticated user)
# GITHUB_FORK_OWNER=your-org

# -----------------------------------------------------------------------------
# Repository configuration — two options, pick one:
#
# OPTION A (PRODUCTION — recommended): Set forge.repos and forge.default_repo
# as Jira project properties on each project. No env vars needed. Forge will
# block workflow and post instructions on the ticket if properties are missing.
#
#   curl -X PUT "https://your-org.atlassian.net/rest/api/3/project/MYPROJ/properties/forge.repos" \
#     -H "Content-Type: application/json" -u "email:token" \
#     -d '["org/repo1", "org/repo2"]'
#
#   curl -X PUT "https://your-org.atlassian.net/rest/api/3/project/MYPROJ/properties/forge.default_repo" \
#     -H "Content-Type: application/json" -u "email:token" \
#     -d '"org/repo1"'
#
# OPTION B (LOCAL DEV): Disable the project property requirement and fall back
# to the env vars below. Set FORGE_REQUIRE_PROJECT_CONFIG=false and fill in
# GITHUB_KNOWN_REPOS / GITHUB_DEFAULT_REPO as a quick local substitute.
# -----------------------------------------------------------------------------

# Default is true (production mode). Set to false for local dev to use env var fallback.
FORGE_REQUIRE_PROJECT_CONFIG=true

# Used only when FORGE_REQUIRE_PROJECT_CONFIG=false (local dev fallback).
# In production, configure forge.repos / forge.default_repo on each Jira project instead.
# GITHUB_KNOWN_REPOS=org/repo1,org/repo2
# GITHUB_DEFAULT_REPO=org/repo1

# =============================================================================
# LLM Configuration
# Supports Claude (via Anthropic API or Vertex AI) and Gemini (via Vertex AI)
# =============================================================================

# Option 1: Direct Anthropic API (Claude models only)
ANTHROPIC_API_KEY=
# Option 2: Google Vertex AI (supports both Claude and Gemini)
ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
ANTHROPIC_VERTEX_REGION=us-east5

# Model for orchestrator (PRD, spec, epic planning)
# Claude models: claude-opus-4-5@20251101, claude-sonnet-4-5@20250929, claude-haiku-4-5@20251001
# Gemini models: gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview
LLM_MODEL=claude-opus-4-5@20251101

# Model for container tasks (code implementation)
# Can use a different model than orchestrator (e.g., for cost/rate limit reasons)
# Leave empty to use LLM_MODEL for everything
CONTAINER_LLM_MODEL=

# Maximum output tokens for LLM responses (default 16384)
# Increase if you see truncated specs/PRDs (default 4096 is often too small)
LLM_MAX_TOKENS=16384

# =============================================================================
# MCP Servers Configuration
# =============================================================================
# MCP servers are configured in mcp-servers.json
# Available servers:
#   - github: Official GitHub MCP (requires Podman/Docker)
#   - gitmcp: GitMCP.io for repo documentation
#   - atlassian: Official Atlassian Rovo MCP (uses JIRA_* credentials above)
#   - context7: Upstash Context7 for library docs
#
# Enable MCP server integrations
AGENT_ENABLE_MCP=true
# MCP servers to enable: '*' for all from mcp-servers.json, or comma-separated list
AGENT_MCP_SERVERS=*
# Restrict MCP tools to read-only operations (no create/update/delete)
AGENT_MCP_READ_ONLY=true
# Path to MCP servers config file (default: mcp-servers.json in project root)
AGENT_MCP_CONFIG_PATH=

# =============================================================================
# Deep Agents Configuration
# =============================================================================
# Enable agent tools (file operations, search, etc.)
AGENT_ENABLE_TOOLS=true
# Allowed tools: '*' for all, or comma-separated list (Read,Write,Edit,Glob,Grep,Bash,WebSearch)
AGENT_ALLOWED_TOOLS=*
# Working directory for agent file operations (empty = current directory)
AGENT_WORKING_DIRECTORY=
# Backend type: filesystem, state, or store
AGENT_BACKEND=filesystem

# Base directory for skill resolution. The resolver finds skills/default/ and
# skills/{project}/ under this path (per-project skills override defaults).
SKILLS_DIR=skills/

# Base directory for worker workspaces. When set, workspaces are created as
# subdirectories here instead of system temp — useful for shared filesystem
# setups where containers and the host worker must see the same checkout.
# WORKSPACE_BASE_DIR=/var/lib/forge/workspaces

# =============================================================================
# Prompt Configuration
# =============================================================================
# Prompt template version to use (e.g., v1, v2)
# This allows A/B testing and gradual rollout of prompt changes
PROMPT_VERSION=v1

# =============================================================================
# Langfuse Configuration (Observability)
# =============================================================================
# Set to true to enable Langfuse tracing
LANGFUSE_ENABLED=true
LANGFUSE_PUBLIC_KEY=your-langfuse-public-key
LANGFUSE_SECRET_KEY=your-langfuse-secret-key
LANGFUSE_HOST=https://cloud.langfuse.com
# Comma-separated list of trace attributes to set as Langfuse tags
# Available values: ticket_key, ticket_type, project_id, workflow_step, repo, pr_number, ci_status, event_source, event_type, llm_model
LANGFUSE_TRACE_TAGS=ticket_key,ticket_type,project_id,workflow_step,repo,pr_number,ci_status,event_source,event_type,llm_model
# Comma-separated list of trace attributes to set as Langfuse metadata
# Available values: ticket_key, ticket_type, project_id, workflow_step, repo, pr_number, ci_status, event_source, event_type, retry_count, system_prompt_length, llm_model
LANGFUSE_TRACE_METADATA=ticket_key,ticket_type,project_id,workflow_step,repo,pr_number,ci_status,event_source,event_type,retry_count,system_prompt_length,llm_model

# OpenTelemetry distributed tracing (separate from Langfuse LLM tracing above)
# Enable/disable OTLP trace export
TRACING_ENABLED=true
# OTLP collector endpoint (leave empty to disable export)
# OTLP_ENDPOINT=http://localhost:4317
# Service name attributed to traces
OTLP_SERVICE_NAME=forge

# Disable the OpenTelemetry SDK env var when not using OTLP (avoids noisy warnings)
OTEL_SDK_DISABLED=true

# =============================================================================
# Container Configuration
# =============================================================================
# Container image for task execution
# - Local development: localhost/forge-dev:latest (build with: podman build -t localhost/forge-dev:latest -f containers/Containerfile containers/)
# - Production: your-registry.com/forge:v1.0.0
# Note: Use localhost/ prefix for local images to avoid podman short-name resolution prompts
CONTAINER_IMAGE=localhost/forge-dev:latest
# Container execution timeout in seconds (default: 2 hours)
CONTAINER_TIMEOUT=7200
# Container resource limits
CONTAINER_MEMORY=4g
CONTAINER_CPUS=2
# Enable LangChain verbose/debug logging in container (shows tool calls, LLM interactions)
CONTAINER_LANGCHAIN_VERBOSE=false
# Keep all containers after exit instead of auto-removing them (useful for debugging).
# When true, containers are preserved and their name is logged with ready-to-run
# inspect commands (podman logs, podman export). Remember to clean up with podman rm.
FORGE_CONTAINER_KEEP=false

# =============================================================================
# Git Configuration (for commits made by Forge)
# =============================================================================
# Git user name and email for commits made inside containers
GIT_USER_NAME=Forge
GIT_USER_EMAIL=forge@example.com

# =============================================================================
# Worker Metrics Configuration
# =============================================================================
# Enable Prometheus metrics endpoint in worker (separate from API server)
WORKER_METRICS_ENABLED=true
# Port for worker Prometheus metrics (default: 8001)
# API server uses port 8000, worker uses 8001 for metrics
WORKER_METRICS_PORT=8001

# =============================================================================
# Application Configuration
# =============================================================================
LOG_LEVEL=INFO
# Path to log file (empty = stdout only)
# LOG_FILE=/var/log/forge/forge.log
# Maximum retry attempts for autonomous CI fixes
CI_FIX_MAX_RETRIES=5
# Comma-separated substrings of CI check names to ignore (permanently-pending meta-checks).
# Checks containing any of these substrings are skipped during CI evaluation.
CI_IGNORED_CHECKS=tide
# Webhook acknowledgment timeout in seconds
WEBHOOK_ACK_TIMEOUT=0.5