docs: add environment variables section to CLI reference#1713
Merged
Conversation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
b909e3a to
3618a7d
Compare
Contributor
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an Environment Variables section to the AWF CLI reference so users can understand which env vars affect CLI behavior (auto-detection, API target overrides, audit output, and API-proxy credential handling), addressing #1562.
Changes:
- Updates CLI reference frontmatter to mention environment variables.
- Inserts a new “Environment Variables” section between “Options Details” and “Exit Codes”.
- Documents auto-detection, API target override, audit, and API proxy credential env vars with tables and admonitions.
Show a summary per file
| File | Description |
|---|---|
| docs-site/src/content/docs/reference/cli-reference.md | Adds an Environment Variables section + updates page description to include env vars. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (5)
docs-site/src/content/docs/reference/cli-reference.md:766
- The
GITHUB_SERVER_URLdescription is incomplete vs actual behavior: when it’s a*.ghe.comtenant, AWF auto-adds not only the tenant andapi.<tenant>domains, but also the Copilot API and Copilot telemetry subdomains (e.g.,copilot-api.<tenant>andcopilot-telemetry-service.<tenant>). Documenting those explicitly would better match the implementation and avoid users under-allowlisting domains.
This issue also appears on line 767 of the same file.
--allow-domains custom-llm.example.com \
-- command
docs-site/src/content/docs/reference/cli-reference.md:767
- The
ENGINE_API_TARGETrow is quite vague compared to what AWF actually adds. The code extracts the hostname (and base domain when the host isapi.*) and also auto-adds required Copilot domains (e.g.,api.githubcopilot.com,api.enterprise.githubcopilot.com,telemetry.enterprise.githubcopilot.com). Consider calling those out so users know what will be included automatically.
**docs-site/src/content/docs/reference/cli-reference.md:771**
* This file consistently uses titled admonitions (e.g., `:::note[Incompatible with --build-local]`, `:::danger[Security Risk]`), but this new block uses `:::note` without a title. To keep formatting consistent (and avoid any parser/theme edge cases), consider adding a bracketed title here as well.
--rate-limit-rpm <n>
Maximum number of requests per minute per provider. Rate limiting is opt-in — it is only enabled when at least one --rate-limit-* flag is provided.
**docs-site/src/content/docs/reference/cli-reference.md:790**
* The Environment Variables section documents `AWF_AUDIT_DIR`, but the CLI also supports `AWF_SESSION_STATE_DIR` (env fallback for `--session-state-dir`) which affects where Copilot CLI session state is written/preserved. Since this section is intended as a reference for env-driven behavior, it would be good to include `AWF_SESSION_STATE_DIR` (and its corresponding flag) alongside the audit directory variable.
Maximum number of requests per hour per provider.
- Default:
10000(when rate limiting is enabled) - Requires:
--enable-api-proxy
docs-site/src/content/docs/reference/cli-reference.md:803
- The Credential Isolation admonition says credentials are “never exposed to the agent container”. In practice, when
--enable-api-proxyis on, the agent may still receive placeholder values for compatibility (e.g.,COPILOT_GITHUB_TOKENis set to a placeholder to prevent--env-allleaks, and other tooling uses placeholder auth tokens). Consider tightening the wording to clarify that the real secret values are never exposed, rather than implying the env vars are entirely absent.
- **Default:** `52428800` (~50 MB, when rate limiting is enabled)
- **Requires:** `--enable-api-proxy`
- Files reviewed: 1/1 changed files
- Comments generated: 0
Contributor
🔥 Smoke Test Results
PR: docs: add environment variables section to CLI reference Overall: PASS
|
Contributor
Smoke Test Results
Overall: PASS
|
Contributor
|
Smoke Test Results
|
Contributor
Smoke Test: GitHub Actions Services Connectivity
All three checks failed. The services are not reachable from this environment —
|
Contributor
🏗️ Build Test Suite Results
Overall: 8/8 ecosystems passed — ✅ PASS
|
Mossaka
commented
Apr 6, 2026
Comment on lines
+928
to
+939
| ### Credentials (API Proxy Sidecar) | ||
|
|
||
| These variables supply API credentials to the API proxy sidecar when `--enable-api-proxy` is active. | ||
|
|
||
| | Variable | Description | | ||
| |----------|-------------| | ||
| | `OPENAI_API_KEY` | OpenAI API key — held securely in the api-proxy sidecar | | ||
| | `ANTHROPIC_API_KEY` | Anthropic API key — held securely in the api-proxy sidecar | | ||
| | `COPILOT_GITHUB_TOKEN` | GitHub Copilot token — held securely in the api-proxy sidecar | | ||
|
|
||
| :::danger[Credential Isolation] | ||
| When `--enable-api-proxy` is active, these credentials are **never exposed to the agent container**. They are held exclusively in the api-proxy sidecar, which injects them into outbound requests on the agent's behalf. |
Collaborator
Author
There was a problem hiding this comment.
move this to the front of the environemnt variables.
Contributor
There was a problem hiding this comment.
Done in 28bfa46 — moved the Credentials (API Proxy Sidecar) subsection to the front of the Environment Variables section.
Comment on lines
+896
to
+908
| ### Auto-Detection | ||
|
|
||
| These variables are read by AWF to automatically add required domains to the allowlist, particularly for GitHub Enterprise Cloud (GHEC) and GitHub Enterprise Server (GHES) deployments. | ||
|
|
||
| | Variable | Description | | ||
| |----------|-------------| | ||
| | `GITHUB_SERVER_URL` | GHEC tenant URL. When set to a `*.ghe.com` host, AWF auto-adds the tenant and API domains to the allowlist. | | ||
| | `GITHUB_API_URL` | GHEC API URL. Auto-added to the allowlist when the host matches `*.ghe.com`. | | ||
| | `ENGINE_API_TARGET` | GHES API URL. The hostname is extracted and GHES-related domains are added to the allowlist. | | ||
|
|
||
| :::note | ||
| These variables are typically set automatically by GitHub Actions runners. You do not need to configure them manually in most cases. | ||
| ::: |
Collaborator
Author
There was a problem hiding this comment.
delete this sub section
Contributor
There was a problem hiding this comment.
Done in 28bfa46 — deleted the Auto-Detection subsection.
Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/da39fcf1-28e6-429d-8d64-5101360dff71 Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
:::danger), and formatting match the existing file style🤖 Generated with Claude Code