Skip to content

[docs] Self-healing documentation fixes from issue analysis - 2026-03-10 #20412

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Mar 10, 2026
Merged

[docs] Self-healing documentation fixes from issue analysis - 2026-03-10 #20412

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/src/content/docs/reference/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,29 @@ 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

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.
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence uses incorrect verb agreement: “GitHub Agentic Workflows … injects” should be “inject” (plural subject).

Suggested change
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.
GitHub Agentic Workflows automatically inject 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.

Copilot uses AI. Check for mistakes.

| 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:

```yaml
env:
GITHUB_AW: "true"
GH_AW_PHASE: agent # or "detection"
GH_AW_VERSION: "0.40.1"
Comment on lines +107 to +117
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documented example values don’t match the compiled workflows produced by the compiler: lock files show GITHUB_AW: true (unquoted) and GH_AW_VERSION is typically a short build/version string (e.g. 3f30e4d), not necessarily a semver like 0.40.1. Consider updating the table and YAML example to reflect the actual emitted values (or clarify that it may be a commit SHA / dev / release version depending on build).

Suggested change
| `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:
```yaml
env:
GITHUB_AW: "true"
GH_AW_PHASE: agent # or "detection"
GH_AW_VERSION: "0.40.1"
| `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. `"3f30e4d"` | The gh-aw compiler version that generated the workflow (often a short commit SHA, `dev`, or a release version). Useful for conditional logic that depends on a minimum feature version. |
These variables appear alongside other `GH_AW_*` context variables in the compiled workflow:
```yaml
env:
GITHUB_AW: true
GH_AW_PHASE: agent # or "detection"
GH_AW_VERSION: "3f30e4d" # e.g. short commit SHA, dev, or release version

Copilot uses AI. Check for mistakes.
GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
```

> [!NOTE]
> These variables are injected by the compiler and cannot be overridden by user-defined `env:` blocks in the workflow frontmatter.
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The NOTE claims these variables “cannot be overridden by user-defined env: blocks in the workflow frontmatter”, but the compiler currently injects these keys and then merges user-provided engine.env / agent env afterwards (e.g. maps.Copy(env, workflowData.EngineConfig.Env) in pkg/workflow/copilot_engine_execution.go), which allows overriding GITHUB_AW, GH_AW_PHASE, or GH_AW_VERSION. Either adjust the docs to reflect actual precedence, or reserve/validate these names in the compiler so the NOTE stays accurate.

Suggested change
> These variables are injected by the compiler and cannot be overridden by user-defined `env:` blocks in the workflow frontmatter.
> These variables are injected by the compiler as defaults for the engine execution context. They can be overridden by user-defined `engine.env` or agent-specific `env` blocks in the workflow frontmatter, but are not affected by workflow-, job-, or step-level `env:` scopes.

Copilot uses AI. Check for mistakes.

## 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.
Expand Down
Loading