docs: comprehensive environment variables documentation#7039
Open
docs: comprehensive environment variables documentation#7039
Conversation
Expand environment-variables.md from ~12 variables to 100+ organized into 14 sections. Add AGENTS.md maintenance guidelines for keeping env var docs in sync with code changes. Fixes #6652 Co-authored-by: Copilot <[email protected]>
spboyer
requested review from
JeffreyCA,
hemarina,
rajeshkamal5050,
tg-msft and
weikanglim
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Expands azd’s documentation to provide a comprehensive reference for environment variables used across the CLI (and related components), and adds contributor guidance to keep the reference updated over time.
Changes:
- Expanded
cli/azd/docs/environment-variables.mdfrom a short list into a multi-section reference covering many more variables. - Added maintenance guidelines to
cli/azd/AGENTS.mdto ensure new/changed env var usage is reflected in the docs.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| cli/azd/docs/environment-variables.md | Replaces the minimal env var list with a sectioned, table-based reference covering core Azure, config, extensions, auth, telemetry, CI/CD, debug, and test variables. |
| cli/azd/AGENTS.md | Adds documentation standards requiring updates to the env var reference when os.Getenv / os.LookupEnv usage changes. |
Comments suppressed due to low confidence (1)
cli/azd/docs/environment-variables.md:100
AZD_UI_NO_PROMPT_DIALOGis enabled by checking whether the variable is non-empty (os.Getenv(...) != ""), not via boolean parsing. With the current behavior,AZD_UI_NO_PROMPT_DIALOG=falsewould still disable the dialog, so the description should be “if set” (or mention presence-based semantics) rather than “if true”.
| `AZD_UI_NO_PROMPT_DIALOG` | If true, disables prompt dialog UI. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Move AZD_SERVER, AZD_ACCESS_TOKEN, AZD_NO_PROMPT, AZD_ENVIRONMENT, AZD_CWD to Extension Variables section with accurate descriptions - Fix AZD_AUTH_CERT description: base64-encoded DER cert, not a path - Add format/defaults for AZD_EXT_TIMEOUT (integer seconds, default 5s) and AZD_EXTENSION_CACHE_TTL (Go duration, default 4h) - Fix AZD_ALLOW_NON_EMPTY_FOLDER: presence-based, not boolean parsed - Add OIDCREQUESTURI to global cspell dictionary Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
JeffreyCA
reviewed
Mar 9, 2026
Contributor
JeffreyCA
left a comment
JeffreyCA
left a comment
There was a problem hiding this comment.
Thanks for updating this - I had no idea we supported so many variables 😅
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `AZD_ALPHA_ENABLE_<name>` | Enables or disables an alpha feature. `<name>` is the upper-cased name of the feature, with dot `.` characters replaced by underscore `_` characters. | |
Contributor
There was a problem hiding this comment.
Can we also call out the special AZD_ALPHA_ENABLE_ALL, which enables all alpha features?
| | `AZD_DEBUG_EXPERIMENTATION_TAS_ENDPOINT` | Overrides the experimentation TAS endpoint URL. | | ||
| | `AZD_SUBSCRIPTIONS_FETCH_MAX_CONCURRENCY` | Limits the maximum concurrency when fetching subscriptions. | | ||
| | `DEPLOYMENT_STACKS_BYPASS_STACK_OUT_OF_SYNC_ERROR` | If true, bypasses Deployment Stacks out-of-sync errors. | | ||
| | `AGENT_DEFINITION_PATH` | Path to an agent definition file for AI agent workflows. | |
Contributor
There was a problem hiding this comment.
This is specific to the azure.ai.agents extension - we may want to remove this or keep it in a separate section?
Comment on lines
+116
to
+117
| | `TRACEPARENT` | The W3C Trace Context `traceparent` header for distributed tracing. | | ||
| | `TRACESTATE` | The W3C Trace Context `tracestate` header for vendor-specific trace data. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `TRACEPARENT` | The W3C Trace Context `traceparent` header for distributed tracing. | | |
| | `TRACESTATE` | The W3C Trace Context `tracestate` header for vendor-specific trace data. | | |
| | `TRACEPARENT` | The W3C Trace Context `traceparent` header for distributed tracing. Automatically set by `azd` on extension processes for trace propagation. Not typically set by users. | | |
| | `TRACESTATE` | The W3C Trace Context `tracestate` header for vendor-specific trace data. Automatically set by `azd` alongside `TRACEPARENT`. Not typically set by users. | |
| | `DEPLOYMENT_STACKS_BYPASS_STACK_OUT_OF_SYNC_ERROR` | If true, bypasses Deployment Stacks out-of-sync errors. | | ||
| | `AGENT_DEFINITION_PATH` | Path to an agent definition file for AI agent workflows. | | ||
|
|
||
| ## Test Variables |
Contributor
There was a problem hiding this comment.
There's also UPDATE_SNAPSHOTS for updating test snapshots
JeffreyCA
reviewed
Mar 9, 2026
| | `AZD_TEST_HTTPS_PROXY` | The HTTPS proxy URL for tests. | | ||
| | `AZD_TEST_DOCKER_E2E` | If true, enables Docker-based end-to-end tests. | | ||
| | `AZD_FUNC_TEST` | If true, indicates functional test mode. | | ||
| | `AZURE_RECORD_MODE` | Sets the record mode for Azure SDK test recordings. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `AZURE_RECORD_MODE` | Sets the record mode for Azure SDK test recordings. | | |
| | `AZURE_RECORD_MODE` | Sets the record mode for Azure SDK test recordings. Valid values: `live`, `playback`, `record`. | |
Apply corrections from JeffreyCA and Copilot review: - Fix AZD_AUTH_CERT description (base64 DER, not path) - Clarify AZD_EXT_TIMEOUT units (seconds) and AZD_EXTENSION_CACHE_TTL format - Fix AZD_ALLOW_NON_EMPTY_FOLDER to presence-based semantics - Clarify extension framework vars (AZD_SERVER, AZD_ACCESS_TOKEN) - Add AZD_ALPHA_ENABLE_ALL - Move azure.ai.agents vars to Extension-Specific section - Fix TRACEPARENT/TRACESTATE descriptions - Add UPDATE_SNAPSHOTS, fix AZURE_RECORD_MODE description Co-authored-by: Copilot <[email protected]>
wbreza
approved these changes
Mar 11, 2026
Contributor
wbreza
left a comment
wbreza
left a comment
There was a problem hiding this comment.
📋 Code Review — PR #7039
Thanks for taking the time to better our docs! This is a solid effort expanding environment variable documentation from ~12 to 100+ entries.
I verified the documented variables against the codebase and found high accuracy — all documented env vars are confirmed present in the source code.
✅ What Looks Good
- All documented env vars verified against the codebase with 100% accuracy
- Prior review feedback from Copilot and @JeffreyCA has been thoroughly addressed
- Excellent organization into 14 well-structured sections
- AGENTS.md maintenance guidelines set a great precedent for keeping docs current
- Debug and Test sections properly marked with unsupported/internal-only warnings
Summary
| Priority | Count |
|---|---|
| Medium | 2 |
| Low | 2 |
| Total | 4 |
Overall Assessment: Approve — minor suggestions for completeness and precision.
| | `AZURE_RESOURCE_GROUP` | The default resource group name. | | ||
| | `AZURE_CONTAINER_REGISTRY_ENDPOINT` | The endpoint of the Azure Container Registry. | | ||
| | `AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN` | The default domain of the Container Apps environment. | | ||
| | `AZURE_APP_SERVICE_DASHBOARD_URI` | The URI for the Azure App Service dashboard. | |
Contributor
There was a problem hiding this comment.
[Medium] Description is slightly misleading
The internal constant for this variable is AppServiceAspireDashboardUrlEnvVarName, indicating it's specifically for the .NET Aspire dashboard URL on App Service, not a generic App Service dashboard.
Consider updating the description to be more precise:
Suggested change
| | `AZURE_APP_SERVICE_DASHBOARD_URI` | The URI for the Azure App Service dashboard. | | |
| | `AZURE_APP_SERVICE_DASHBOARD_URI` | The URI for the .NET Aspire dashboard hosted on Azure App Service. | |
| | `AZURE_OIDC_REQUEST_TOKEN` | The request token for Azure OIDC in GitHub Actions. | | ||
| | `AZURE_OIDC_REQUEST_URL` | The request URL for Azure OIDC in GitHub Actions. | | ||
| | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | The GitHub Actions OIDC request token. | | ||
| | `ACTIONS_ID_TOKEN_REQUEST_URL` | The GitHub Actions OIDC request URL. | |
Contributor
There was a problem hiding this comment.
[Medium] Missing CODESPACES environment variable
The CODESPACES env var is read in production code (internal/tracing/resource/exec_environment.go and pkg/tools/github/github.go) to detect GitHub Codespaces. It affects tracing metadata and GitHub CLI behavior.
Consider adding it to this section:
| `CODESPACES` | Set to `true` when running in GitHub Codespaces. Used by azd for environment detection and tracing. |
| | `AZD_EXT_DEBUG` | If true, enables debug output for extensions. | | ||
| | `AZD_EXTENSION_CACHE_TTL` | Time-to-live for extension cache entries, parsed with Go's `time.ParseDuration` format (for example, `30m`, `4h`). Defaults to `4h`. | | ||
|
|
||
| ## Extension-Specific Variables |
Contributor
There was a problem hiding this comment.
[Low] Extension-specific section organization
Building on @JeffreyCA's earlier comment — it might be worth considering whether extension-specific env vars should live here or in the extension's own documentation, especially as more extensions are added. Either approach works; just worth establishing the pattern now.
| | `AZD_DEBUG_LOGIN_FORCE_SUBSCRIPTION_REFRESH` | If true, forces a refresh of the subscription list on login. | | ||
| | `AZD_DEBUG_SYNTHETIC_SUBSCRIPTION` | If set, provides a synthetic subscription for testing. | | ||
| | `AZD_DEBUG_NO_ALPHA_WARNINGS` | If true, suppresses alpha feature warnings. | | ||
| | `AZD_DEBUG_PROVISION_PROGRESS_DISABLE` | If true, disables provision progress display. | |
Contributor
There was a problem hiding this comment.
[Low] Minor description precision
This variable is read by both the Bicep provider (pkg/infra/provisioning/bicep/bicep_provider.go) and the Dev Center provisioner (pkg/devcenter/provision_provider.go). The current description is accurate but could note it applies to both provisioning backends.
Co-authored-by: Copilot <[email protected]>
Collaborator
Azure Dev CLI Install InstructionsInstall scriptsMacOS/Linux
bash: pwsh: WindowsPowerShell install MSI install Standalone Binary
MSI
Documentationlearn.microsoft.com documentationtitle: Azure Developer CLI reference
|
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.
Expand
environment-variables.mdfrom ~12 variables to 100+ organized into 14 sections covering all env vars used by azd. Add AGENTS.md maintenance guidelines.Recreated from #6653 (auto-closed by inactivity bot) with updates for new variables added since.
Fixes #6652