Text of github.github.com › gh-aw › reference › environment-variables as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Environment Variables | GitHub Agentic Workflows

Skip to main content 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 Section titled “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 gateway configuration MCP Tools tools.<name>.env MCP server process MCP server secrets MCP Scripts mcp-scripts.<name>.env MCP script 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 Strict mode rejects credential expressions in workflow-level env , including secrets references and github.token in either dot or bracket notation.

Whole-context github references and context-wide wildcard projections such as github.* and toJSON(github.*) are also treated as credential references. Non-strict mode emits a warning. The same validation applies to non-exempt keys in engine.env . Supported credential keys in engine.env remain allowed; strict mode requires AWF v0.25.3 or newer to exclude those values from the agent sandbox. Invalid expressions in env or engine.env fail compilation in either mode.

Actions bracket indexes use single-quoted strings, for example github['repository'] ; double-quoted indexes are invalid. Example Configurations Section titled “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 }} --- Agent Step Summary ( GITHUB_STEP_SUMMARY ) Section titled “Agent Step Summary (GITHUB_STEP_SUMMARY)” Agents can write markdown content to the $GITHUB_STEP_SUMMARY environment variable to publish a formatted summary visible in the GitHub Actions run view.

Inside the AWF sandbox, $GITHUB_STEP_SUMMARY is redirected to a file at /tmp/gh-aw/agent-step-summary.md . After agent execution completes, the framework automatically appends the contents of that file to the real GitHub step summary. Secret redaction runs before the content is published. Example: an agent writing a brief analysis result to the step summary: Terminal window echo " ## Analysis complete " >> " $GITHUB_STEP_SUMMARY " echo " Found 3 issues across 12 files.

" >> " $GITHUB_STEP_SUMMARY " The output appears in the Summary tab of the GitHub Actions workflow run. System-Injected Runtime Variables Section titled “System-Injected Runtime Variables” GitHub Agentic Workflows automatically injects the following environment variables into every agentic engine execution step (both the main agent run and the threat detection run). These variables are read-only from the agent’s perspective and are useful for writing workflows or agents that need to detect their execution context.

Variable Value Description GITHUB_AW "true" Present in every gh-aw engine execution step. Agents can check for this variable to confirm they are running inside a GitHub Agentic Workflow. GH_AW_PHASE "agent" or "detection" Identifies which execution phase is active. "agent" for the main run; "detection" for the threat-detection safety check run that precedes the main run. GH_AW_VERSION e.g. "0.40.1" The gh-aw compiler version that generated the workflow.

Useful for conditional logic that depends on a minimum feature version. These variables appear alongside other GH_AW_* context variables in the compiled workflow: env : GITHUB_AW : " true " GH_AW_PHASE : agent # or "detection" GH_AW_VERSION : " 0.40.1 " GH_AW_PROMPT : /tmp/gh-aw/aw-prompts/prompt.txt Harness Settings and Runtime Tuning Variables Section titled “Harness Settings and Runtime Tuning Variables” The built-in Copilot, Claude, and Codex harnesses expose a small set of supported runtime controls.

Prefer the structured engine.harness frontmatter fields when possible; set the underlying environment variables only when you need a value that is supplied by a GitHub Actions expression or shared across a workflow. Shared harness retry settings Section titled “Shared harness retry settings” These settings apply to the built-in Copilot, Claude, and Codex harnesses. Variable Frontmatter field Default Units / range Description GH_AW_HARNESS_MAX_RETRIES engine.harness.max-retries 3 retry attempts after the initial run; minimum 0 , maximum 100 Maximum number of harness retries.

0 disables retries. Invalid values use the default; values above 100 are clamped to 100 . GH_AW_HARNESS_INITIAL_DELAY_MS engine.harness.initial-delay-ms 5000 milliseconds; minimum 1 Delay before the first retry. Invalid values use the default. GH_AW_HARNESS_BACKOFF_MULTIPLIER engine.harness.backoff-multiplier 2 decimal multiplier; minimum 1 Multiplier applied after each retry. Invalid values use the default. GH_AW_HARNESS_MAX_DELAY_MS engine.harness.max-delay-ms 60000 milliseconds; minimum 1 Maximum retry delay.

Invalid values use the default. If set below GH_AW_HARNESS_INITIAL_DELAY_MS , it is clamped up to the initial delay. Shared post-result watchdog Section titled “Shared post-result watchdog” GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS configures the post-result stdio inactivity watchdog used by the built-in Copilot, Claude, and Codex harnesses. It is measured in milliseconds . The default is 120000 ms (2 minutes), the minimum is 50 ms, and the maximum is 600000 ms (10 minutes).

Unset, non-numeric, zero, and negative values use the default; positive values outside the supported range are clamped. The watchdog is dormant until the agent emits a terminal safe output. noop and ordinary task outputs such as comments, labels, pushes, and pull request creation are terminal. Diagnostic safe outputs such as report_missing_tool , report_missing_data , and report_incomplete are not terminal and do not arm the watchdog by themselves.

After the watchdog arms, any stdout or stderr activity resets the inactivity clock. A quiet child process can therefore be terminated even while it is doing useful CPU or I/O work, such as a monorepo scan, build, or test command that produces no logs. If the watchdog fires after a terminal safe output already exists, the harness may still treat the run as successful because the requested safe output was already produced.

For literal frontmatter values, use engine.harness.watchdog-timeout in seconds. For raw environment variables, use milliseconds: --- env : # Allow quiet monorepo scans and builds after an intermediate safe output. # Workflow-level env is visible to the agent; do not put secrets here. GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS : " 600000 " --- --- engine : id : copilot harness : # Same timeout expr

The rest of this page is on the live site.