Configuration

Configuration

Overview

Every az prototype project is configured through two YAML files stored in the project root:

• prototype.yaml -- The main configuration file. Safe to commit to version control. Contains project settings, AI provider selection, naming strategy, agent configuration, and stage state.
• prototype.secrets.yaml -- Holds sensitive values (API keys, subscription IDs, tokens, service principal credentials). Should be git-ignored. Created automatically when secret values are set.

Both files are managed through the ProjectConfig class, which provides dot-notation access for reading and writing nested values. When you call config.get("ai.provider") or config.set("deploy.subscription", "..."), the class automatically routes values to the correct file.

See also: AI Providers for provider-specific configuration, Naming Strategies for naming configuration, and Templates for workload templates.

Full Config Structure

The complete default configuration created by az prototype init:

project:
  id: ""                        # Auto-generated UUID
  name: ""                      # Project name (set during init)
  location: "eastus"            # Azure region for deployment
  environment: "dev"            # Environment tag (dev, test, staging, prod)
  created: ""                   # ISO 8601 timestamp (auto-set)
  iac_tool: "terraform"         # Infrastructure-as-code tool: terraform | bicep

naming:
  strategy: "microsoft-alz"     # Naming strategy (see Naming-Strategies)
  org: ""                       # Organization prefix for resource names
  env: "dev"                    # Environment abbreviation used in names
  zone_id: "zd"                 # ALZ zone ID (zd=Development, zp=Production, etc.)

ai:
  provider: "copilot"           # AI provider: copilot | github-models | azure-openai
  model: "claude-sonnet-4.5"    # Model to use for AI calls
  azure_openai:
    endpoint: ""                # Azure OpenAI endpoint (*.openai.azure.com)
    deployment: "gpt-4o"        # Deployment name within the Azure OpenAI resource

agents:
  custom_dir: ".prototype/agents/"  # Directory for custom agent definitions
  custom: {}                        # Custom agent registrations
  overrides: {}                     # Override settings for built-in agents

deploy:
  track_changes: true               # Track deployment state changes
  subscription: ""                  # [SECRET] Azure subscription ID
  resource_group: ""                # Target resource group name
  tenant: ""                        # Azure AD tenant
  service_principal:                # [SECRET] Service principal credentials
    client_id: ""
    client_secret: ""
    tenant_id: ""
  generated_secrets: {}             # [SECRET] Secrets generated during deploy

backlog:
  provider: "github"               # Backlog provider: github | azure-devops
  org: ""                           # GitHub org or Azure DevOps org
  project: ""                       # Project/repo name
  token: ""                         # [SECRET] PAT for backlog push

mcp:
  servers: []                       # [SECRET] MCP server configurations
  custom_dir: ".prototype/mcp/"     # Directory for custom MCP handlers

stages:
  init:
    completed: false
    timestamp: null
  design:
    completed: false
    timestamp: null
    iterations: 0
  build:
    completed: false
    timestamp: null
  deploy:
    completed: false
    timestamp: null

Values marked [SECRET] are automatically routed to prototype.secrets.yaml.

Secrets Routing

Sensitive values are automatically separated from the main config file. The routing is determined by the SECRET_KEY_PREFIXES list. Any key that starts with one of the following prefixes is stored in prototype.secrets.yaml instead of prototype.yaml:

Prefix	What it covers
ai.azure_openai.api_key	Azure OpenAI API key (note: API key auth is actually blocked -- use az login)
deploy.subscription	Azure subscription ID
deploy.service_principal	Service principal client ID, client secret, and tenant ID
deploy.generated_secrets	Secrets generated during deployment (connection strings, keys, etc.)
backlog.token	Personal access token for GitHub or Azure DevOps
mcp.servers	MCP server configurations (may contain auth tokens)

When you set a value via az prototype config set or the ProjectConfig.set() API:

1. The value is stored in the in-memory unified config for immediate access.
2. If the key matches a secret prefix, it is written to prototype.secrets.yaml.
3. The main prototype.yaml is saved with secret leaf values replaced by empty strings.

When loading, prototype.secrets.yaml is overlaid onto prototype.yaml so callers always see a unified view.

Config Commands

az prototype config init

Interactive questionnaire that walks through standard project configuration questions and creates prototype.yaml. Use this when you want a guided setup experience instead of manually editing the config.

az prototype config show

Displays the current merged configuration. Secret values stored in prototype.secrets.yaml are included in the output (they are not masked). This shows the unified view of both files.

az prototype config show

az prototype config get KEY

Retrieves a single value by its dot-separated key path.

az prototype config get --key ai.provider
# Output: copilot

az prototype config get --key project.location
# Output: eastus

az prototype config get --key naming.strategy
# Output: microsoft-alz

az prototype config set KEY VALUE

Sets a configuration value. The value is validated against security constraints before being persisted. Secret keys are automatically routed to the secrets file.

az prototype config set --key ai.provider --value github-models
az prototype config set --key project.location --value westus2
az prototype config set --key deploy.subscription --value "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Validation rules enforced at set time:

• ai.provider must be one of: copilot, github-models, azure-openai. Non-Azure providers (openai, anthropic, cohere, etc.) are blocked.
• ai.azure_openai.endpoint must match https://<resource>.openai.azure.com/. Public OpenAI endpoints are blocked.
• ai.azure_openai.api_key is rejected entirely -- authentication uses Azure identity (az login).
• project.iac_tool must be terraform or bicep.
• project.location must be a known Azure region.

Dot-Notation Examples

The config system uses dot-separated keys to navigate the nested YAML structure:

# AI provider settings
az prototype config set --key ai.provider --value copilot
az prototype config set --key ai.model --value claude-sonnet-4
az prototype config get --key ai.provider

# Project settings
az prototype config set --key project.name --value my-project
az prototype config set --key project.location --value westeurope
az prototype config set --key project.iac_tool --value bicep

# Naming strategy (see Naming-Strategies)
az prototype config set --key naming.strategy --value microsoft-caf
az prototype config set --key naming.org --value contoso
az prototype config set --key naming.env --value prod

# Azure OpenAI (see AI-Providers)
az prototype config set --key ai.azure_openai.endpoint --value https://my-resource.openai.azure.com/
az prototype config set --key ai.azure_openai.deployment --value gpt-4o

# Deployment
az prototype config set --key deploy.subscription --value "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
az prototype config set --key deploy.resource_group --value rg-my-project-dev

# Backlog integration
az prototype config set --key backlog.provider --value github
az prototype config set --key backlog.org --value my-org
az prototype config set --key backlog.token --value ghp_xxxxxxxxxxxxx

Config File Locations

Both configuration files are stored in the project root directory (the directory where az prototype init was run):

my-project/
  prototype.yaml              # Main config -- commit to git
  prototype.secrets.yaml      # Secrets -- add to .gitignore
  .prototype/                 # Internal state directory
    agents/                   # Custom agent definitions
    mcp/                      # Custom MCP handler plugins
    state/                    # Stage state files (design, build, deploy, backlog)
    templates/                # Custom workload templates

Ensure prototype.secrets.yaml is listed in your .gitignore:

prototype.secrets.yaml

The prototype.yaml file is safe to commit and share -- it contains no credentials or sensitive data when the secrets routing is working correctly.