Configuration¶

All configuration is via environment variables in .env. See .env.example in the repository for the complete list with comments.

Required Variables¶

Jira¶

GitHub¶

LLM¶

Choose one backend explicitly. Gemini 3.5 Flash through Vertex AI is recommended.

LLM_BACKEND=vertex-ai
GOOGLE_CLOUD_PROJECT=your-gcp-project
GOOGLE_CLOUD_LOCATION=global
LLM_MODEL=gemini-3.5-flash

LLM_BACKEND=google-genai
GOOGLE_API_KEY=your-google-api-key
LLM_MODEL=gemini-3.5-flash

LLM_BACKEND=anthropic
ANTHROPIC_API_KEY=your-anthropic-api-key
LLM_MODEL=claude-sonnet-4-6

LLM_BACKEND and LLM_MODEL are required for legacy configuration. A complete MODEL_CONNECTIONS plus MODEL_DEFAULT configuration replaces them and derives the runtime backend, model, Vertex project, and location. Provider credentials must use the provider-native variables shown above; legacy aliases are not supported. Forge validates the backend, credentials, and model compatibility at startup.

The legacy CONTAINER_LLM_MODEL override remains supported. For exact per-stage selection, administrators can define JSON MODEL_CONNECTIONS, MODEL_DEFAULT, and MODEL_POLICY values. Connections contain a backend, provider location, model allowlist, and declared capabilities—never a credential value. Each backend uses its existing provider-native environment credential. Jira projects then set forge.model_policy, restricted to those connections and models:

MODEL_CONNECTIONS={"vertex-global":{"backend":"vertex-ai","project":"my-gcp-project","location":"global","allowed_models":["gemini-3.5-flash","claude-sonnet-5"],"capabilities":["tools"]}}
MODEL_DEFAULT={"connection":"vertex-global","model":"gemini-3.5-flash"}
MODEL_POLICY={"generate_prd":{"connection":"vertex-global","model":"claude-sonnet-5"},"generate_spec":{"connection":"vertex-global","model":"gemini-3.5-flash"}}

forge project-setup MYPROJ \
  --model generate_prd=vertex-production:gemini-3.5-pro \
  --model implement_task=anthropic-production:claude-sonnet-4-6

# Set a separate project-wide fallback (individual --model overrides still win)
forge project-setup MYPROJ \
  --model-all vertex-production:gemini-3.5-pro

# Remove one stage override and preserve the rest
forge project-setup MYPROJ --remove-model generate_prd

# Delete all per-stage overrides
forge project-setup MYPROJ --clear-model-policy

# Delete the project-wide fallback
forge project-setup MYPROJ --clear-model-default

# Validate against the local runtime configuration and print every target
forge get-config MYPROJ --models

Project overrides require administrators to configure MODEL_CONNECTIONS. The user-facing project-setup command validates policy syntax and canonical stage names but does not require access to the Forge deployment's connection registry. Forge validates connection names, model allowlists, backends, and capabilities when it executes a stage. Invalid runtime policy fails closed and reports the available configured connections and models to Jira and, when an active PR exists, GitHub. The implicit legacy connection remains restricted to LLM_MODEL and CONTAINER_LLM_MODEL and is never exposed to Jira project policy.

Canonical policy keys are deliberately specific; runtime prompt, skill, and graph-node names are not accepted in Jira configuration:

Unknown keys fail validation instead of silently using the default target.

Keeping artifact generation, revision, and Q&A on one model¶

Revisions reuse the artifact's generation policy key. For example, both initial PRD generation and later ! revision requests resolve generate_prd. Questions submitted with ? do not regenerate the artifact and resolve the separate answer_question key. Configure both keys when the answer must use the same model that created the PRD:

MODEL_POLICY={"generate_prd":{"connection":"vertex-global","model":"claude-opus-4-6"},"answer_question":{"connection":"vertex-global","model":"claude-opus-4-6"}}

forge project-setup MYPROJ \
  --model generate_prd=vertex-global:claude-opus-4-6 \
  --model answer_question=vertex-global:claude-opus-4-6

The same pattern applies to generate_spec, decompose_epics, and generate_tasks: revisions reuse their generation key, while Q&A uses answer_question. Task-takeover artifact questions are the exception and use task_takeover_question.

Related actions that use separate policy keys¶

Some user-visible flows contain multiple model invocations with intentionally different responsibilities. Forge resolves each invocation independently, so they may use different models unless every related key is mapped to the same target:

Using different models for these keys is supported and can optimize cost or quality. When context continuity or consistent judgment is more important, assign all keys in the flow to the same connection and model. Run forge get-config MYPROJ --models to display the effective target for every key before testing a workflow.

Forge owns stage capability requirements. Every stage requires a connection declaring "capabilities": ["tools"] except the explicitly tool-free text or classification stages automated_review_triage, proposal_review_triage, generate_pr_description, and sync_pr_description. Jira policy cannot weaken that requirement. Per-target max_output_tokens is limited to 131072.

Resolution is project stage override (forge.model_policy), then the separate project-wide fallback (forge.model_default), then the deployment stage mapping (MODEL_POLICY), then the deployment default (MODEL_DEFAULT). Project policy does not use a * key. --model-all writes forge.model_default and does not modify per-stage overrides. When --model-policy and --model are combined, individual --model entries overwrite matching JSON keys. Used without --model-policy, --model preserves the project's other existing stage overrides; --model-policy deliberately replaces the full stage property. --remove-model removes only the named stage and deletes forge.model_policy when no overrides remain. --clear-model-policy deletes all per-stage overrides, while --clear-model-default independently deletes the project-wide fallback. When MODEL_CONNECTIONS is configured, Forge fetches the Jira project policy before each host or container agent execution, so changes apply automatically to the next stage or retry. The target remains fixed during that execution's internal model/tool loop. Legacy and global-only configurations make no extra Jira policy request. Projects without forge.model_policy fall back to the global stage mapping, then the global default, and finally the legacy LLM_BACKEND/LLM_MODEL settings.

Redis¶

Per-Project Repository Configuration¶

Set these properties per Jira project via the REST API:

# Available repos for this project
curl -X PUT \
  "https://your-org.atlassian.net/rest/api/3/project/MYPROJ/properties/forge.repos" \
  -H "Content-Type: application/json" \
  -u "you@example.com:YOUR_API_TOKEN" \
  -d '["org/repo1", "org/repo2"]'

# Alternatively, configure a repository with additional metadata (like enabling draft PRs) using an object:
curl -X PUT \
  "https://your-org.atlassian.net/rest/api/3/project/MYPROJ/properties/forge.repos" \
  -H "Content-Type: application/json" \
  -u "you@example.com:YOUR_API_TOKEN" \
  -d '[
    "org/repo1",
    {
      "name": "org/repo2",
      "draft": true
    }
  ]'

# Default repo when no explicit assignment is made
curl -X PUT \
  "https://your-org.atlassian.net/rest/api/3/project/MYPROJ/properties/forge.default_repo" \
  -H "Content-Type: application/json" \
  -u "you@example.com:YOUR_API_TOKEN" \
  -d '"org/repo1"'

Local Development Overrides¶

Use these to skip the Jira project property requirement during local development:

CI and Validation¶

Container Execution¶

Auto-Review¶

Settings for the automatic review loop that runs after skill execution. See the Auto-Review Guide for details.

Observability¶

Langfuse Tracing¶

Grafana Dashboards¶

These variables are used by docker-compose.yml, devtools/docker-compose.dev.yml, and devtools/grafana/compose.grafana.yml.

MCP Servers¶

MCP server configuration lives in mcp-servers.json, not .env. See the MCP servers section of the repository.