Skip to content

Environment Configuration

Environment Configuration

Environment variables can be configured at multiple levels in Prodigy workflows, providing flexible control over workflow execution across different environments and contexts.

Source: Configuration structures defined in src/cook/environment/config.rs:11-144, workflow configuration in src/config/workflow.rs:12-39.

Overview

Prodigy supports comprehensive environment configuration including: - Global environment variables with static, dynamic, and conditional values - Secret management with automatic log masking - Environment profiles for different deployment contexts - Environment files (.env format) - Step-level environment overrides - Variable interpolation in commands

This subsection provides a quick introduction to environment configuration. For comprehensive coverage, see the Environment chapter.

Global Environment Variables

Define environment variables in the env: block at the workflow root. Variables can be static strings, dynamically computed from commands, or conditionally set based on expressions.

Source: workflows/environment-example.yml:4-18

env:
  # Static environment variables
  NODE_ENV: production
  API_URL: https://api.example.com

  # Dynamic environment variable (computed from command)
  WORKERS:
    command: "nproc 2>/dev/null || echo 4"
    cache: true

  # Conditional environment variable
  DEPLOY_ENV:
    condition: "${branch} == 'main'"
    when_true: "production"
    when_false: "staging"

Type Definitions (src/cook/environment/config.rs:38-81): - EnvValue::Static(String) - Static string value - EnvValue::Dynamic(DynamicEnv) - Computed from command with optional caching - EnvValue::Conditional(ConditionalEnv) - Based on condition expression

Environment Files

Load environment variables from .env format files using the env_files: field.

Source: workflows/environment-example.yml:25-27, src/cook/environment/config.rs:22-23

env_files:
  - .env.production
  - .env.local

Variables from env files are merged with global env variables, with explicit env: block taking precedence.

For detailed information about .env file format and loading behavior, see Environment Files.

Secrets Management

Secret environment variables are automatically masked in all log output, preventing accidental credential leaks.

Source: workflows/mapreduce-env-example.yml:23-26, src/cook/environment/config.rs:86-112

secrets:
  # Simple secret reference
  API_KEY: "${env:SECRET_API_KEY}"

  # Provider-based secret
  API_TOKEN:
    provider: env
    key: "GITHUB_TOKEN"

Secret Providers (src/cook/environment/config.rs:101-112): - env - Environment variable - file - File-based secret - vault - HashiCorp Vault - aws - AWS Secrets Manager - Custom providers

For comprehensive secrets management documentation, see Secrets Management.

Environment Profiles

Profiles enable different environment configurations for various deployment contexts (development, staging, production).

Source: workflows/environment-example.yml:30-39, src/cook/environment/config.rs:116-124

profiles:
  development:
    description: "Development environment with debug enabled"
    NODE_ENV: development
    API_URL: http://localhost:3000
    DEBUG: "true"

  production:
    description: "Production environment"
    NODE_ENV: production
    API_URL: https://api.example.com
    DEBUG: "false"

Activate a profile: 

# Via command line flag
prodigy run workflow.yml --profile development

# Via environment variable
export PRODIGY_PROFILE=production
prodigy run workflow.yml

For detailed profile configuration and best practices, see Environment Profiles.

Step-Level Environment Overrides

Commands can define their own environment variables that override global and profile settings.

Source: workflows/environment-example.yml:47-60, src/cook/environment/config.rs:126-144

commands:
  - name: "Build frontend"
    shell: "echo 'Building with NODE_ENV='$NODE_ENV"
    env:
      BUILD_TARGET: production
      OPTIMIZE: "true"
    working_dir: ./frontend

  - name: "Run tests"
    shell: "pytest"
    env:
      PYTHONPATH: "./src:./tests"
      TEST_ENV: "true"
    working_dir: ./backend
    temporary: true  # Environment restored after this step

Step Environment Fields (src/cook/environment/config.rs:128-144): - env: HashMap<String, String> - Step-specific variables - working_dir: Option<PathBuf> - Working directory for this step - clear_env: bool - Clear parent environment before applying step env - temporary: bool - Restore environment after step completes

For detailed step-level configuration, see Per-Command Environment Overrides.

Variable Interpolation

Environment variables can be referenced in commands using two syntaxes: $VAR or ${VAR}.

Source: workflows/mapreduce-env-example.yml:44-80

env:
  PROJECT_NAME: "my-project"
  OUTPUT_DIR: "output"

commands:
  # Both syntaxes work
  - shell: "echo Starting $PROJECT_NAME"
  - shell: "echo Output directory: ${OUTPUT_DIR}"

  # Use ${} for complex expressions
  - shell: "cp summary.json ${OUTPUT_DIR}/${PROJECT_NAME}-report.json"

Variable interpolation is available in: - Shell commands - Claude commands - File paths - MapReduce configuration (max_parallel, timeout, etc.)

For comprehensive variable interpolation documentation, see Variable Interpolation.

Environment Precedence

When the same variable is defined at multiple levels, precedence is:

  1. Step-level env (highest priority)
  2. Profile env
  3. Global env
  4. System environment (lowest priority)

Source: Precedence logic in src/cook/environment/builder.rs:48-53, tests in tests/environment_workflow_test.rs:62-132

For detailed precedence rules and examples, see Environment Precedence.

MapReduce Environment Variables

Environment variables are available across all MapReduce workflow phases: setup, map, reduce, and merge.

Source: workflows/mapreduce-env-example.yml:1-95, src/config/mapreduce.rs:24-38

name: mapreduce-workflow
mode: mapreduce

env:
  PROJECT_NAME: "my-project"
  MAX_RETRIES: "3"

setup:
  - shell: "echo Starting $PROJECT_NAME"

map:
  agent_template:
    - claude: "/process --project $PROJECT_NAME --retries $MAX_RETRIES"

reduce:
  - shell: "echo Completed $PROJECT_NAME workflow"

merge:
  commands:
    - shell: "echo Merging $PROJECT_NAME changes"

For comprehensive MapReduce environment documentation, see MapReduce Environment Variables.

Complete Example

This example demonstrates multiple environment features working together.

Source: Complete workflow in workflows/environment-example.yml:1-70

# Global environment with static, dynamic, and conditional values
env:
  NODE_ENV: production
  API_URL: https://api.example.com

  WORKERS:
    command: "nproc 2>/dev/null || echo 4"
    cache: true

  DEPLOY_ENV:
    condition: "${branch} == 'main'"
    when_true: "production"
    when_false: "staging"

# Secrets (masked in logs)
secrets:
  API_KEY: "${env:SECRET_API_KEY}"

# Environment files
env_files:
  - .env.production

# Profiles
profiles:
  development:
    NODE_ENV: development
    API_URL: http://localhost:3000
    DEBUG: "true"

# Commands with step-level overrides
commands:
  - name: "Build"
    shell: "npm run build"
    env:
      BUILD_TARGET: production
    working_dir: ./frontend

  - name: "Deploy"
    shell: "echo Deploying to $DEPLOY_ENV"