Skip to content

Available Fields

Available Fields

Standard workflows support these top-level fields:

Field Type Required Description
name String No Workflow name for identification (defaults to "default")
commands Array Yes* List of commands to execute sequentially
env Map No Global environment variables
secrets Map No Secret environment variables (masked in logs)
env_files Array No Paths to .env files to load
profiles Map No Named environment profiles for different contexts
merge MergeWorkflow No Custom merge workflow for worktree integration

Source: Type definitions from src/config/workflow.rs:11-38

Note: commands is only required in the full format. Use the simple array format for quick workflows without environment configuration. Use the full format when you need environment variables, profiles, or custom merge workflows.

Field Relationships and Precedence

Understanding how fields interact is important for effective workflow configuration:

  1. Environment Variable Resolution Order:
  2. Command-level env overrides all other sources
  3. Profile-specific variables (when a profile is active) override global env
  4. Global env variables provide base configuration

  5. Variables from env_files are loaded first and can be overridden

  6. Secrets vs. Environment Variables:

  7. secrets are a special type of environment variable that are masked in logs and output
  8. Both env and secrets are available to all commands

  9. Secrets take precedence over regular environment variables with the same name

  10. Profile Activation:

  11. Profiles are activated via --profile <name> CLI flag
  12. Profile variables merge with global env, with profile values taking precedence
  13. Common use case: different configurations for dev, staging, and production

Format Examples

Simple Array Format (from examples/standard-workflow.yml):

- shell: echo "Starting code analysis..."
- shell: cargo check --quiet
- shell: echo "Workflow complete"

Use this format when: - You don't need environment variables - You have a quick, straightforward sequence of commands - You want minimal YAML verbosity

Full Format with Environment (from workflows/environment-example.yml):

name: production-deploy

env:
  NODE_ENV: production
  API_URL: https://api.example.com

secrets:
  API_KEY: "${env:SECRET_API_KEY}"

env_files:
  - .env.production

profiles:
  development:
    NODE_ENV: development
    API_URL: http://localhost:3000
  staging:
    NODE_ENV: staging
    API_URL: https://staging.api.example.com

commands:
  - shell: echo "Deploying with NODE_ENV=$NODE_ENV"
  - shell: npm run build
  - shell: npm run deploy

Use this format when: - You need environment variables - You have different configurations for different environments (profiles) - You need to mask sensitive values (secrets) - You want to load variables from .env files