docs: add AWF pipeline environment variable lifecycle reference

[Copilot]

The environment variable landscape across the gh-aw ↔ AWF pipeline (Actions runner → DIFC proxy → compiler → AWF → agent container) was entirely undocumented as a unified lifecycle, causing repeated production issues where DIFC-rewritten values (e.g. GH_HOST=localhost:18443, GITHUB_API_URL=https://localhost:18443/...) leaked into agent containers.

Adds docs/AWF_PIPELINE_ENVIRONMENT_VARIABLES.md covering:

• Per-stage variable tables — what each pipeline stage (Actions runner, DIFC proxy, gh-aw compiler, AWF docker-manager, API proxy sidecar) sets, rewrites, or strips, with github.com / GHES / GHEC columns where values differ
• Agent container identity variables — how GH_HOST is sanitized from GITHUB_SERVER_URL, and the remaining gap where GITHUB_API_URL / GITHUB_GRAPHQL_URL may still carry DIFC-rewritten localhost values under --env-all
• API proxy sidecar split — placeholder credentials in the agent container vs. real credentials held by the sidecar; COPILOT_API_TARGET three-tier derivation rules per instance type
• EXCLUDED_ENV_VARS — always-excluded base set, --enable-api-proxy additions, and variables that are not excluded but require active sanitization
• One-shot token protection — current protected list and two known gaps (GITHUB_MCP_SERVER_TOKEN, GH_AW_GITHUB_TOKEN)
• Variable precedence ordering — 5-stage resolution order (base → --env-all → --env-file → --env → post-processing overrides)
• ASCII lifecycle diagram and outstanding gaps table (leakage, missing one-shot tokens, no Gemini API proxy)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• example.com
  • Triggering command: /tmp/go-build73518018/b334/launcher.test /tmp/go-build73518018/b334/launcher.test -test.testlogfile=/tmp/go-build73518018/b334/testlog.txt -test.paniconexit0 -test.timeout=10m0s 1654�� ache/go/1.25.8/x64/src/runtime/c-c=4 (dns block)
• invalid-host-that-does-not-exist-12345.com
  • Triggering command: /tmp/go-build73518018/b319/config.test /tmp/go-build73518018/b319/config.test -test.testlogfile=/tmp/go-build73518018/b319/testlog.txt -test.paniconexit0 -test.timeout=10m0s abis�� ternal/engine/interpreter/compiler.go ternal/engine/interpreter/format.go x_amd64/compile (dns block)
• nonexistent.local
  • Triggering command: /tmp/go-build73518018/b334/launcher.test /tmp/go-build73518018/b334/launcher.test -test.testlogfile=/tmp/go-build73518018/b334/testlog.txt -test.paniconexit0 -test.timeout=10m0s 1654�� ache/go/1.25.8/x64/src/runtime/c-c=4 (dns block)
• slow.example.com
  • Triggering command: /tmp/go-build73518018/b334/launcher.test /tmp/go-build73518018/b334/launcher.test -test.testlogfile=/tmp/go-build73518018/b334/testlog.txt -test.paniconexit0 -test.timeout=10m0s 1654�� ache/go/1.25.8/x64/src/runtime/c-c=4 (dns block)
• this-host-does-not-exist-12345.com
  • Triggering command: /tmp/go-build73518018/b343/mcp.test /tmp/go-build73518018/b343/mcp.test -test.testlogfile=/tmp/go-build73518018/b343/testlog.txt -test.paniconexit0 -test.timeout=10m0s go_.�� rotocol/go-sdk@v1.4.1/mcp/client.go rotocol/go-sdk@v1.4.1/mcp/cmd.go x_amd64/vet -I /tmp/go-build270--version -I x_amd64/vet -I g_.a 1654201/b151/ x_amd64/vet -o ernal/proxy /tmp/ccnzrWtf.s x_amd64/vet (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[Copilot]

Pull request overview

Adds a new unified documentation reference describing how environment variables propagate and are transformed across the gh-aw ↔ AWF execution pipeline, with emphasis on preventing DIFC-proxy–rewritten values from leaking into agent containers.

Changes:

• Introduces docs/AWF_PIPELINE_ENVIRONMENT_VARIABLES.md with stage-by-stage env var tables and lifecycle diagram.
• Documents known gaps (e.g., GITHUB_API_URL/GITHUB_GRAPHQL_URL leakage under --env-all, incomplete one-shot token coverage).
• Describes API proxy sidecar split, Copilot API target derivation, and variable precedence.

Comments suppressed due to low confidence (2)

docs/AWF_PIPELINE_ENVIRONMENT_VARIABLES.md:121

• References to deriveCopilotApiTarget() in server.js (and similarly extractGhecDomainsFromServerUrl() in cli.ts below) point to files that are not in this repo. Please add a link to the external source (repo + path), or adjust the wording to avoid implying the code is located here.

The `deriveCopilotApiTarget()` function in the API proxy sidecar (`server.js`) resolves the upstream Copilot API endpoint using the following three-tier priority:

docs/AWF_PIPELINE_ENVIRONMENT_VARIABLES.md:287

• Cross-repo references like gh-aw-firewall#1492 / gh-aw#23461 may not auto-link from this repo and are ambiguous without an owner. Prefer fully-qualified refs (e.g., github/gh-aw-firewall#1492, github/gh-aw#23461) or full URLs so readers can click through reliably.

- gh-aw-firewall#1492 — `GH_HOST` proxy passthrough bug
- github/gh-aw-mcpg#1493 — PR implementing `GH_HOST` sanitization
- gh-aw-firewall#1452 — `GH_HOST` auto-injection interaction with `--env-all`
- gh-aw-firewall#1481 — `--env-all` exposing secrets; one-shot token list incomplete
- gh-aw#23461 — User-reported `GH_HOST` breakage
- gh-aw#23092 — Safe outputs env vars not reaching agent container

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This doc cites implementation files like docker-manager.ts / docker-compose.yml generation. Those files don’t exist in this repository, so readers can’t trace the source. Consider linking to the AWF repository/path (or explicitly stating the repo + commit/branch) where these files live, to keep the reference actionable.

This issue also appears in the following locations of the same file:

• line 120
• line 282

Suggested change

	AWF's `docker-manager.ts` generates these environment variables for the **agent container** via `docker-compose.yml`.
	Within the separate AWF service (implemented outside this repository), the `docker-manager.ts` component generates these environment variables for the **agent container** via its `docker-compose.yml` definition.