Environment Variables

Environment variables in GitHub Agentic Workflows can be defined at multiple scopes, each serving a specific purpose in the workflow lifecycle. Variables defined at more specific scopes override those at more general scopes, following GitHub Actions conventions while adding AWF-specific contexts.

Environment Variable Scopes

GitHub Agentic Workflows supports environment variables in 13 distinct contexts:

Scope	Syntax	Context	Typical Use
Workflow-level	`env:`	All jobs	Shared configuration
Job-level	`jobs.<job_id>.env`	All steps in job	Job-specific config
Step-level	`steps[*].env`	Single step	Step-specific config
Engine	`engine.env`	AI engine	Engine secrets, timeouts
Container	`container.env`	Container runtime	Container settings
Services	`services.<id>.env`	Service containers	Database credentials
Sandbox Agent	`sandbox.agent.env`	Sandbox runtime	Sandbox configuration
Sandbox MCP	`sandbox.mcp.env`	Model Context Protocol (MCP) gateway	MCP debugging
MCP Tools	`tools.<name>.env`	MCP server process	MCP server secrets
Safe Inputs	`safe-inputs.<name>.env`	Safe-input execution	Tool-specific tokens
Safe Outputs Global	`safe-outputs.env`	All safe-output jobs	Shared safe-output config
Safe Outputs Job	`safe-outputs.jobs.<name>.env`	Specific safe-output job	Job-specific config
GitHub Actions Step	`githubActionsStep.env`	Pre-defined steps	Step configuration

Example Configurations

Workflow-level shared configuration:

---
env:
  NODE_ENV: production
  API_ENDPOINT: https://api.example.com
---

Job-specific overrides:

---
jobs:
  validation:
    env:
      VALIDATION_MODE: strict
    steps:
      - run: npm run build
        env:
          BUILD_ENV: production  # Overrides job and workflow levels
---

AWF-specific contexts:

---
# Engine configuration
engine:
  id: copilot
  env:
    OPENAI_API_KEY: ${{ secrets.CUSTOM_KEY }}

# MCP server with secrets
tools:
  database:
    command: npx
    args: ["-y", "mcp-server-postgres"]
    env:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}

# Safe outputs with custom PAT
safe-outputs:
  create-issue:
  env:
    GITHUB_TOKEN: ${{ secrets.CUSTOM_PAT }}
---

Precedence Rules

Environment variables follow a most-specific-wins model, consistent with GitHub Actions. Variables at more specific scopes completely override variables with the same name at less specific scopes.

General Precedence (Highest to Lowest)

Step-level (steps[*].env, githubActionsStep.env)
Job-level (jobs.<job_id>.env)
Workflow-level (env:)

Safe Outputs Precedence

Job-specific (safe-outputs.jobs.<job_name>.env)
Global (safe-outputs.env)
Workflow-level (env:)

Context-Specific Scopes

These scopes are independent and operate in different contexts: engine.env, container.env, services.<id>.env, sandbox.agent.env, sandbox.mcp.env, tools.<tool>.env, safe-inputs.<tool>.env.

Override Example

---
env:
  API_KEY: default-key
  DEBUG: "false"

jobs:
  test:
    env:
      API_KEY: test-key    # Overrides workflow-level
      EXTRA: "value"
    steps:
      - run: |
          # API_KEY = "test-key" (job-level override)
          # DEBUG = "false" (workflow-level inherited)
          # EXTRA = "value" (job-level)
---

Frontmatter Reference - Complete frontmatter configuration
Safe Outputs - Safe output environment configuration
Sandbox - Sandbox environment variables
Tools - MCP tool configuration
Safe Inputs - Safe input tool configuration
GitHub Actions Environment Variables - GitHub Actions documentation

Environment Variables