From 583e19371c89b605a0e42219e8c3223375640b4e Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Fri, 6 Mar 2026 22:03:37 -0500 Subject: [PATCH 1/7] docs: comprehensive environment variables documentation 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 <223556219+Copilot@users.noreply.github.com> --- cli/azd/AGENTS.md | 9 ++ cli/azd/docs/environment-variables.md | 216 ++++++++++++++++++++++++-- 2 files changed, 210 insertions(+), 15 deletions(-) diff --git a/cli/azd/AGENTS.md b/cli/azd/AGENTS.md index 73f4217bd09..a95ed63e5a7 100644 --- a/cli/azd/AGENTS.md +++ b/cli/azd/AGENTS.md @@ -195,6 +195,15 @@ func (a *myAction) Run(ctx context.Context) (*actions.ActionResult, error) { - **No dead references**: Don't reference files, scripts, directories, or workflows that don't exist in the PR. If a README lists `scripts/generate-report.ts`, it must exist. If a CI table lists `eval-human.yml`, it must be included - **PR description accuracy**: Keep the PR description in sync with the actual implementation. If the description says "server-side filtering" but the code does client-side filtering, update the description +#### Environment Variables Documentation + +The file `cli/azd/docs/environment-variables.md` is the single source of truth for every environment +variable `azd` reads. When adding or modifying an `os.Getenv` / `os.LookupEnv` call: + +1. Add the variable to the appropriate section in `environment-variables.md`. +2. Include a one-line description that explains what it controls and its default if non-obvious. +3. Place debug/internal variables under **Debug Variables** with the unsupported warning. + ### Modern Go This project uses Go 1.26. Use modern standard library features: diff --git a/cli/azd/docs/environment-variables.md b/cli/azd/docs/environment-variables.md index e96152a41be..7e7b423af66 100644 --- a/cli/azd/docs/environment-variables.md +++ b/cli/azd/docs/environment-variables.md @@ -1,21 +1,207 @@ # Environment Variables -## Environment variables used with azd +Comprehensive reference of environment variables used by `azd`. -Environment variables that can be used to configure `azd` behavior, usually set within a shell or terminal. For environment variables that accept a boolean, the values `1, t, T, TRUE, true, True` are accepted as "true"; the values: `0, f, F, FALSE, false, False` are all accepted as "false". +For environment variables that accept a boolean, the values `1, t, T, TRUE, true, True` are accepted +as "true"; the values `0, f, F, FALSE, false, False` are all accepted as "false". -- `AZD_ALPHA_ENABLE_`: Enables or disables an alpha feature. `` is the upper-cased name of the feature, with dot `.` characters replaced by underscore `_` characters. -- `AZD_AUTH_ENDPOINT`: The [External Authentication](./external-authentication.md) endpoint. -- `AZD_AUTH_KEY`: The [External Authentication](./external-authentication.md) shared key. -- `AZD_BUILDER_IMAGE`: The builder docker image used to perform Dockerfile-less builds. -- `AZD_CONFIG_DIR`: The file path of the user-level configuration directory. -- `AZD_DEMO_MODE`: If true, enables demo mode. This hides personal output, such as subscription IDs, from being displayed in output. -- `AZD_FORCE_TTY`: If true, forces `azd` to write terminal-style output. -- `AZD_IN_CLOUDSHELL`: If true, `azd` runs with Azure Cloud Shell specific behavior. -- `AZD_SKIP_UPDATE_CHECK`: If true, skips the out-of-date update check output that is typically printed at the end of the command. +## Core Azure Variables -For tools that are auto-acquired by `azd`, you are able to configure the following environment variables to use a different version of the tool installed on the machine: +These variables are typically set by infrastructure provisioning outputs and stored in the `.env` file +for each environment. -- `AZD_BICEP_TOOL_PATH`: The Bicep tool override path. The direct path to `bicep` or `bicep.exe`. -- `AZD_GH_TOOL_PATH`: The `gh` tool override path. The direct path to `gh` or `gh.exe`. -- `AZD_PACK_TOOL_PATH`: The `pack` tool override path. The direct path to `pack` or `pack.exe`. +| Variable | Description | +| --- | --- | +| `AZURE_ENV_NAME` | The name of the active azd environment. | +| `AZURE_LOCATION` | The default Azure region for resource deployment. | +| `AZURE_SUBSCRIPTION_ID` | The Azure subscription ID used for deployment. | +| `AZURE_TENANT_ID` | The Microsoft Entra tenant ID. | +| `AZURE_PRINCIPAL_ID` | The object ID of the signed-in principal. | +| `AZURE_PRINCIPAL_TYPE` | The type of the signed-in principal (e.g., `User`, `ServicePrincipal`). | +| `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. | +| `AZURE_AKS_CLUSTER_NAME` | The name of the Azure Kubernetes Service cluster. | + +## Dev Center Variables + +Variables for [Azure Dev Center](https://learn.microsoft.com/azure/dev-box/overview-what-is-microsoft-dev-box) +integration. + +| Variable | Description | +| --- | --- | +| `AZURE_DEVCENTER_NAME` | The name of the Dev Center instance. | +| `AZURE_DEVCENTER_PROJECT` | The Dev Center project name. | +| `AZURE_DEVCENTER_CATALOG` | The catalog name within Dev Center. | +| `AZURE_DEVCENTER_ENVIRONMENT_TYPE` | The environment type in Dev Center (e.g., `Dev`, `Test`, `Prod`). | +| `AZURE_DEVCENTER_ENVIRONMENT_DEFINITION` | The environment definition name. | +| `AZURE_DEVCENTER_ENVIRONMENT_USER` | The user identity for the Dev Center environment. | + +## General Configuration + +| Variable | Description | +| --- | --- | +| `AZD_CONFIG_DIR` | The file path of the user-level configuration directory. | +| `AZD_DEMO_MODE` | If true, enables demo mode. This hides personal output, such as subscription IDs, from being displayed in output. | +| `AZD_FORCE_TTY` | If true, forces `azd` to write terminal-style output. | +| `AZD_IN_CLOUDSHELL` | If true, `azd` runs with Azure Cloud Shell specific behavior. | +| `AZD_SKIP_UPDATE_CHECK` | If true, skips the out-of-date update check output that is typically printed at the end of the command. | +| `AZD_CONTAINER_RUNTIME` | The container runtime to use (e.g., `docker`, `podman`). | +| `AZD_ALLOW_NON_EMPTY_FOLDER` | If true, allows `azd init` to run in a non-empty directory without prompting. | +| `AZD_NO_PROMPT` | If true, disables all interactive prompts. | +| `AZD_ENVIRONMENT` | Specifies the default environment name for azd commands. | +| `AZD_CWD` | Overrides the current working directory for azd commands. | +| `AZD_SERVER` | If true, starts `azd` in server mode. | +| `AZD_ACCESS_TOKEN` | An access token used for authenticating API requests in server mode. | +| `AZD_BUILDER_IMAGE` | The builder docker image used to perform Dockerfile-less builds. | + +## Alpha Features + +| Variable | Description | +| --- | --- | +| `AZD_ALPHA_ENABLE_` | Enables or disables an alpha feature. `` is the upper-cased name of the feature, with dot `.` characters replaced by underscore `_` characters. | + +## External Authentication + +Variables for [External Authentication](./external-authentication.md) integration. + +| Variable | Description | +| --- | --- | +| `AZD_AUTH_ENDPOINT` | The [External Authentication](./external-authentication.md) endpoint. | +| `AZD_AUTH_KEY` | The [External Authentication](./external-authentication.md) shared key. | +| `AZD_AUTH_CERT` | The [External Authentication](./external-authentication.md) certificate path. | + +## Tool Configuration + +For tools that are auto-acquired by `azd`, the following environment variables configure the path to a +specific version of the tool installed on the machine. + +| Variable | Description | +| --- | --- | +| `AZD_BICEP_TOOL_PATH` | The Bicep tool override path. The direct path to `bicep` or `bicep.exe`. | +| `AZD_GH_TOOL_PATH` | The `gh` tool override path. The direct path to `gh` or `gh.exe`. | +| `AZD_PACK_TOOL_PATH` | The `pack` tool override path. The direct path to `pack` or `pack.exe`. | + +## Extension Variables + +| Variable | Description | +| --- | --- | +| `AZD_EXT_TIMEOUT` | Timeout duration for extension operations. | +| `AZD_EXT_DEBUG` | If true, enables debug output for extensions. | +| `AZD_EXTENSION_CACHE_TTL` | The time-to-live for extension cache entries. | + +## UI Prompt Integration + +| Variable | Description | +| --- | --- | +| `AZD_UI_PROMPT_ENDPOINT` | The endpoint for external UI prompt service integration. | +| `AZD_UI_PROMPT_KEY` | The authentication key for the external UI prompt service. | +| `AZD_UI_NO_PROMPT_DIALOG` | If true, disables prompt dialog UI. | + +## Telemetry & Tracing + +| Variable | Description | +| --- | --- | +| `AZURE_DEV_COLLECT_TELEMETRY` | If false, disables telemetry collection. Telemetry is enabled by default. | +| `AZURE_DEV_USER_AGENT` | Appends a custom string to the `User-Agent` header sent with Azure requests. | +| `TRACEPARENT` | The W3C Trace Context `traceparent` header for distributed tracing. | +| `TRACESTATE` | The W3C Trace Context `tracestate` header for vendor-specific trace data. | + +## CI/CD Variables + +These variables are read by `azd` to detect and integrate with CI/CD systems. + +### Azure Pipelines + +| Variable | Description | +| --- | --- | +| `TF_BUILD` | Set to `True` when running in Azure Pipelines. | +| `BUILD_BUILDID` | The build ID in Azure Pipelines. | +| `BUILD_BUILDNUMBER` | The build number in Azure Pipelines. | +| `SYSTEM_ACCESSTOKEN` | The access token for Azure Pipelines service connections. | +| `SYSTEM_TEAMPROJECTID` | The Team Project ID in Azure DevOps. | +| `SYSTEM_OIDCREQUESTURI` | The OIDC request URI for federated identity in Azure Pipelines. | +| `AZURESUBSCRIPTION_CLIENT_ID` | The client ID from the Azure service connection. | +| `AZURESUBSCRIPTION_TENANT_ID` | The tenant ID from the Azure service connection. | +| `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID` | The service connection ID in Azure DevOps. | +| `AZURESUBSCRIPTION_SUBSCRIPTION_ID` | The subscription ID from the Azure service connection. | + +### GitHub Actions + +| Variable | Description | +| --- | --- | +| `GITHUB_ACTIONS` | Set to `true` when running in GitHub Actions. | +| `GITHUB_RUN_ID` | The unique ID of the current GitHub Actions workflow run. | +| `AZURE_OIDC_TOKEN` | An OIDC token for Azure federated credential authentication. | +| `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. | + +### General CI + +| Variable | Description | +| --- | --- | +| `CI` | Set to `true` when running in a generic CI environment. | + +## Terraform Provider Variables + +These variables are used by the Terraform provider integration to authenticate with Azure. + +| Variable | Description | +| --- | --- | +| `ARM_TENANT_ID` | The Azure tenant ID for Terraform Azure provider. | +| `ARM_CLIENT_ID` | The Azure client ID for Terraform Azure provider. | +| `ARM_CLIENT_SECRET` | The Azure client secret for Terraform Azure provider. | +| `ARM_SUBSCRIPTION_ID` | The Azure subscription ID for Terraform Azure provider. | + +## Console & Terminal + +| Variable | Description | +| --- | --- | +| `NO_COLOR` | If set, disables color output. See [no-color.org](https://no-color.org). | +| `FORCE_COLOR` | If set, forces color output regardless of terminal detection. | +| `COLUMNS` | Overrides the detected terminal width (in columns). | +| `TERM` | The terminal type. Used to detect terminal capabilities. | +| `BROWSER` | The browser command to use for opening URLs (e.g., during `azd auth login`). | + +## Debug Variables + +> **Warning**: Debug variables are unsupported and may change or be removed without notice. + +| Variable | Description | +| --- | --- | +| `AZD_DEBUG` | If true, enables debug mode. | +| `AZD_DEBUG_LOG` | If true, enables debug-level logging. | +| `AZD_DEBUG_TELEMETRY` | If true, enables debug-level telemetry output. | +| `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. | +| `AZD_DEBUG_DOTNET_APPHOST_USE_FIXED_MANIFEST` | If true, uses a fixed manifest for .NET Aspire app host. | +| `AZD_DEBUG_DOTNET_APPHOST_IGNORE_UNSUPPORTED_RESOURCES` | If true, ignores unsupported resources in .NET Aspire app host. | +| `AZD_DEBUG_SERVER_DEBUG_ENDPOINTS` | If true, enables debug endpoints in server mode. | +| `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. | + +## Test Variables + +> **Warning**: Test variables are used by the `azd` test suite only and are not intended for end users. + +| Variable | Description | +| --- | --- | +| `AZD_TEST_CLIENT_ID` | The client ID for test authentication. | +| `AZD_TEST_TENANT_ID` | The tenant ID for test authentication. | +| `AZD_TEST_AZURE_SUBSCRIPTION_ID` | The Azure subscription ID for tests. | +| `AZD_TEST_AZURE_LOCATION` | The Azure location for tests. | +| `AZD_TEST_CLI_VERSION` | Overrides the CLI version reported during tests. | +| `AZD_TEST_FIXED_CLOCK_UNIX_TIME` | Sets a fixed clock time (Unix epoch) for deterministic tests. | +| `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. | +| `CLI_TEST_AZD_PATH` | Overrides the `azd` binary path used in CLI tests. | +| `CLI_TEST_SKIP_BUILD` | If true, skips building `azd` before running tests. | From 8fbb60af3e6d172b65043e4dc3e8c671e19543c3 Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Sat, 7 Mar 2026 09:02:41 -0500 Subject: [PATCH 2/7] address PR review feedback - 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 <223556219+Copilot@users.noreply.github.com> --- cli/azd/.vscode/cspell.yaml | 1 + cli/azd/docs/environment-variables.md | 28 +++++++++++++++++---------- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/cli/azd/.vscode/cspell.yaml b/cli/azd/.vscode/cspell.yaml index f4f38677b7c..6d65b2581a6 100644 --- a/cli/azd/.vscode/cspell.yaml +++ b/cli/azd/.vscode/cspell.yaml @@ -37,6 +37,7 @@ words: # Looks like the protogen has a spelling error for panics - pancis - Paren + - OIDCREQUESTURI - pkgux - ppid - PPID diff --git a/cli/azd/docs/environment-variables.md b/cli/azd/docs/environment-variables.md index 7e7b423af66..596d522abde 100644 --- a/cli/azd/docs/environment-variables.md +++ b/cli/azd/docs/environment-variables.md @@ -48,14 +48,22 @@ integration. | `AZD_IN_CLOUDSHELL` | If true, `azd` runs with Azure Cloud Shell specific behavior. | | `AZD_SKIP_UPDATE_CHECK` | If true, skips the out-of-date update check output that is typically printed at the end of the command. | | `AZD_CONTAINER_RUNTIME` | The container runtime to use (e.g., `docker`, `podman`). | -| `AZD_ALLOW_NON_EMPTY_FOLDER` | If true, allows `azd init` to run in a non-empty directory without prompting. | -| `AZD_NO_PROMPT` | If true, disables all interactive prompts. | -| `AZD_ENVIRONMENT` | Specifies the default environment name for azd commands. | -| `AZD_CWD` | Overrides the current working directory for azd commands. | -| `AZD_SERVER` | If true, starts `azd` in server mode. | -| `AZD_ACCESS_TOKEN` | An access token used for authenticating API requests in server mode. | +| `AZD_ALLOW_NON_EMPTY_FOLDER` | If set, allows `azd init` to run in a non-empty directory without prompting. | | `AZD_BUILDER_IMAGE` | The builder docker image used to perform Dockerfile-less builds. | +## Extension Variables + +These variables are set and consumed by azd extension hosts (for example, IDE/editor integrations) +and the azd extension framework. They are not intended to be configured as general CLI settings. + +| Variable | Description | +| --- | --- | +| `AZD_NO_PROMPT` | If true, disables interactive prompts. Typically set by extension hosts for non-interactive behavior. | +| `AZD_ENVIRONMENT` | The azd environment name provided by the extension host when invoking azd. | +| `AZD_CWD` | The working directory path used by the extension host when invoking azd. | +| `AZD_SERVER` | The address (e.g., `localhost:12345`) of the azd extension server for gRPC communication. Set by the extension framework. | +| `AZD_ACCESS_TOKEN` | A JWT used by the extension host to authenticate gRPC calls to the azd extension server. Generated by the extension framework. | + ## Alpha Features | Variable | Description | @@ -70,7 +78,7 @@ Variables for [External Authentication](./external-authentication.md) integratio | --- | --- | | `AZD_AUTH_ENDPOINT` | The [External Authentication](./external-authentication.md) endpoint. | | `AZD_AUTH_KEY` | The [External Authentication](./external-authentication.md) shared key. | -| `AZD_AUTH_CERT` | The [External Authentication](./external-authentication.md) certificate path. | +| `AZD_AUTH_CERT` | The [External Authentication](./external-authentication.md) client certificate, provided as a base64-encoded DER X.509 certificate string. When set, `AZD_AUTH_ENDPOINT` must use HTTPS. | ## Tool Configuration @@ -83,13 +91,13 @@ specific version of the tool installed on the machine. | `AZD_GH_TOOL_PATH` | The `gh` tool override path. The direct path to `gh` or `gh.exe`. | | `AZD_PACK_TOOL_PATH` | The `pack` tool override path. The direct path to `pack` or `pack.exe`. | -## Extension Variables +## Extension Configuration | Variable | Description | | --- | --- | -| `AZD_EXT_TIMEOUT` | Timeout duration for extension operations. | +| `AZD_EXT_TIMEOUT` | Timeout for extension operations, in integer seconds (e.g., `10`). Defaults to 5 seconds. | | `AZD_EXT_DEBUG` | If true, enables debug output for extensions. | -| `AZD_EXTENSION_CACHE_TTL` | The time-to-live for extension cache entries. | +| `AZD_EXTENSION_CACHE_TTL` | Time-to-live for extension cache entries, as a Go duration string (e.g., `30m`, `4h`). Defaults to `4h`. | ## UI Prompt Integration From 600e24f7b447eaa79f304cc186be6362cb882891 Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Sun, 8 Mar 2026 12:00:42 -0400 Subject: [PATCH 3/7] ci: retrigger Windows build check Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> From 06e382599caec4a425bfd1462d8f98ab330df1d3 Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Tue, 10 Mar 2026 19:03:30 -0700 Subject: [PATCH 4/7] docs: address PR review feedback on environment-variables.md 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 <223556219+Copilot@users.noreply.github.com> --- cli/azd/docs/environment-variables.md | 36 +++++++++++++++++++++------ 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/cli/azd/docs/environment-variables.md b/cli/azd/docs/environment-variables.md index 596d522abde..a9596f232ec 100644 --- a/cli/azd/docs/environment-variables.md +++ b/cli/azd/docs/environment-variables.md @@ -61,13 +61,14 @@ and the azd extension framework. They are not intended to be configured as gener | `AZD_NO_PROMPT` | If true, disables interactive prompts. Typically set by extension hosts for non-interactive behavior. | | `AZD_ENVIRONMENT` | The azd environment name provided by the extension host when invoking azd. | | `AZD_CWD` | The working directory path used by the extension host when invoking azd. | -| `AZD_SERVER` | The address (e.g., `localhost:12345`) of the azd extension server for gRPC communication. Set by the extension framework. | -| `AZD_ACCESS_TOKEN` | A JWT used by the extension host to authenticate gRPC calls to the azd extension server. Generated by the extension framework. | +| `AZD_SERVER` | The address (e.g., `localhost:12345`) of the azd extension server for gRPC communication. Injected and consumed by the extension framework; not typically set by users directly. | +| `AZD_ACCESS_TOKEN` | A JWT used to authenticate gRPC calls to the azd extension server. Injected and consumed by the extension framework; not typically set by users directly. | ## Alpha Features | Variable | Description | | --- | --- | +| `AZD_ALPHA_ENABLE_ALL` | Enables all alpha features at once. | | `AZD_ALPHA_ENABLE_` | Enables or disables an alpha feature. `` is the upper-cased name of the feature, with dot `.` characters replaced by underscore `_` characters. | ## External Authentication @@ -78,7 +79,7 @@ Variables for [External Authentication](./external-authentication.md) integratio | --- | --- | | `AZD_AUTH_ENDPOINT` | The [External Authentication](./external-authentication.md) endpoint. | | `AZD_AUTH_KEY` | The [External Authentication](./external-authentication.md) shared key. | -| `AZD_AUTH_CERT` | The [External Authentication](./external-authentication.md) client certificate, provided as a base64-encoded DER X.509 certificate string. When set, `AZD_AUTH_ENDPOINT` must use HTTPS. | +| `AZD_AUTH_CERT` | The [External Authentication](./external-authentication.md) client certificate, provided as a base64-encoded DER certificate string. When set, `AZD_AUTH_ENDPOINT` must use HTTPS. | ## Tool Configuration @@ -95,9 +96,27 @@ specific version of the tool installed on the machine. | Variable | Description | | --- | --- | -| `AZD_EXT_TIMEOUT` | Timeout for extension operations, in integer seconds (e.g., `10`). Defaults to 5 seconds. | +| `AZD_EXT_TIMEOUT` | Timeout for extension operations, parsed as an integer number of seconds (for example, `10`). Defaults to `5` seconds; this is not a duration string, so values like `10m` are not valid. | | `AZD_EXT_DEBUG` | If true, enables debug output for extensions. | -| `AZD_EXTENSION_CACHE_TTL` | Time-to-live for extension cache entries, as a Go duration string (e.g., `30m`, `4h`). Defaults to `4h`. | +| `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 + +### azure.ai.agents + +| Variable | Description | +| --- | --- | +| `AZURE_AI_PROJECT_ID` | The Microsoft Foundry project resource ID used by the `azure.ai.agents` extension. | +| `AZURE_AI_PROJECT_ENDPOINT` | The Microsoft Foundry project endpoint used by the `azure.ai.agents` extension. | +| `AZURE_AI_PROJECT_PRINCIPAL_ID` | The principal ID associated with the Microsoft Foundry project identity. | +| `AZURE_AI_ACCOUNT_NAME` | The Microsoft Foundry account name associated with the project. | +| `AZURE_AI_PROJECT_NAME` | The Microsoft Foundry project name. | +| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | The default model deployment name used for generated agent code and templates. | +| `AZURE_AI_PROJECT_ACR_CONNECTION_NAME` | The Azure Container Registry connection name used by the extension for hosted agents. | +| `AI_PROJECT_DEPLOYMENTS` | JSON-encoded deployment metadata populated by the extension for agent workflows. | +| `AI_PROJECT_DEPENDENT_RESOURCES` | JSON-encoded dependent resource metadata populated by the extension for agent workflows. | +| `ENABLE_HOSTED_AGENTS` | If set, indicates that hosted agents are enabled for the current azd environment. | +| `ENABLE_CONTAINER_AGENTS` | If set, indicates that container agents are enabled for the current azd environment. | ## UI Prompt Integration @@ -113,8 +132,8 @@ specific version of the tool installed on the machine. | --- | --- | | `AZURE_DEV_COLLECT_TELEMETRY` | If false, disables telemetry collection. Telemetry is enabled by default. | | `AZURE_DEV_USER_AGENT` | Appends a custom string to the `User-Agent` header sent with Azure requests. | -| `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. | ## CI/CD Variables @@ -210,6 +229,7 @@ These variables are used by the Terraform provider integration to authenticate w | `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. | +| `UPDATE_SNAPSHOTS` | If set, updates test snapshots when running snapshot-based tests. | +| `AZURE_RECORD_MODE` | Sets the record mode for Azure SDK test recordings. Valid values: `live`, `playback`, `record`. | | `CLI_TEST_AZD_PATH` | Overrides the `azd` binary path used in CLI tests. | | `CLI_TEST_SKIP_BUILD` | If true, skips building `azd` before running tests. | From fda21e5be32b08ccb338c077e60568f9e27e87df Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Wed, 11 Mar 2026 13:18:38 -0700 Subject: [PATCH 5/7] ci: re-trigger build for flaky Mac/Windows failures Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> From 9f6df26f10c789943608831a0482e41dd9afb1e5 Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Thu, 26 Mar 2026 10:57:43 -0700 Subject: [PATCH 6/7] docs: address review feedback on env vars documentation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- cli/azd/docs/environment-variables.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/cli/azd/docs/environment-variables.md b/cli/azd/docs/environment-variables.md index a9596f232ec..e34ec48b11b 100644 --- a/cli/azd/docs/environment-variables.md +++ b/cli/azd/docs/environment-variables.md @@ -21,7 +21,7 @@ for each environment. | `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. | +| `AZURE_APP_SERVICE_DASHBOARD_URI` | The URI for the .NET Aspire dashboard hosted on Azure App Service. | | `AZURE_AKS_CLUSTER_NAME` | The name of the Azure Kubernetes Service cluster. | ## Dev Center Variables @@ -102,6 +102,9 @@ specific version of the tool installed on the machine. ## Extension-Specific Variables +> **Note**: These variables are defined and consumed by individual azd extensions. As the extension +> ecosystem grows, extension-specific variables may move to each extension's own documentation. + ### azure.ai.agents | Variable | Description | @@ -117,6 +120,7 @@ specific version of the tool installed on the machine. | `AI_PROJECT_DEPENDENT_RESOURCES` | JSON-encoded dependent resource metadata populated by the extension for agent workflows. | | `ENABLE_HOSTED_AGENTS` | If set, indicates that hosted agents are enabled for the current azd environment. | | `ENABLE_CONTAINER_AGENTS` | If set, indicates that container agents are enabled for the current azd environment. | +| `AGENT_DEFINITION_PATH` | Path to an agent definition file for AI agent workflows. | ## UI Prompt Integration @@ -132,8 +136,8 @@ specific version of the tool installed on the machine. | --- | --- | | `AZURE_DEV_COLLECT_TELEMETRY` | If false, disables telemetry collection. Telemetry is enabled by default. | | `AZURE_DEV_USER_AGENT` | Appends a custom string to the `User-Agent` header sent with Azure requests. | -| `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. | +| `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. | ## CI/CD Variables @@ -166,6 +170,12 @@ These variables are read by `azd` to detect and integrate with CI/CD systems. | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | The GitHub Actions OIDC request token. | | `ACTIONS_ID_TOKEN_REQUEST_URL` | The GitHub Actions OIDC request URL. | +### GitHub Codespaces + +| Variable | Description | +| --- | --- | +| `CODESPACES` | Set to `true` when running in GitHub Codespaces. Used by `azd` for environment detection and tracing. | + ### General CI | Variable | Description | @@ -205,14 +215,13 @@ These variables are used by the Terraform provider integration to authenticate w | `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. | +| `AZD_DEBUG_PROVISION_PROGRESS_DISABLE` | If true, disables provision progress display. Read by both the Bicep provider and the Dev Center provisioner. | | `AZD_DEBUG_DOTNET_APPHOST_USE_FIXED_MANIFEST` | If true, uses a fixed manifest for .NET Aspire app host. | | `AZD_DEBUG_DOTNET_APPHOST_IGNORE_UNSUPPORTED_RESOURCES` | If true, ignores unsupported resources in .NET Aspire app host. | | `AZD_DEBUG_SERVER_DEBUG_ENDPOINTS` | If true, enables debug endpoints in server mode. | | `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. | ## Test Variables From c506593dbf64497e9d95643b8b6c59a374afdecb Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Mon, 30 Mar 2026 15:11:00 -0400 Subject: [PATCH 7/7] docs: address jongio review feedback on env vars - Fix AZD_UI_NO_PROMPT_DIALOG: presence-checked, not boolean - Fix FORCE_COLOR: exact '1' check, not generic boolean - Add AZD_COPILOT_CLI_PATH to tool path variables - Add AZD_DEPLOY_TIMEOUT to general configuration Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- cli/azd/docs/environment-variables.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/cli/azd/docs/environment-variables.md b/cli/azd/docs/environment-variables.md index e34ec48b11b..f85fcdc540f 100644 --- a/cli/azd/docs/environment-variables.md +++ b/cli/azd/docs/environment-variables.md @@ -50,6 +50,7 @@ integration. | `AZD_CONTAINER_RUNTIME` | The container runtime to use (e.g., `docker`, `podman`). | | `AZD_ALLOW_NON_EMPTY_FOLDER` | If set, allows `azd init` to run in a non-empty directory without prompting. | | `AZD_BUILDER_IMAGE` | The builder docker image used to perform Dockerfile-less builds. | +| `AZD_DEPLOY_TIMEOUT` | Timeout for deployment operations, parsed as an integer number of seconds (for example, `1200`). Defaults to `1200` seconds (20 minutes). | ## Extension Variables @@ -91,6 +92,7 @@ specific version of the tool installed on the machine. | `AZD_BICEP_TOOL_PATH` | The Bicep tool override path. The direct path to `bicep` or `bicep.exe`. | | `AZD_GH_TOOL_PATH` | The `gh` tool override path. The direct path to `gh` or `gh.exe`. | | `AZD_PACK_TOOL_PATH` | The `pack` tool override path. The direct path to `pack` or `pack.exe`. | +| `AZD_COPILOT_CLI_PATH` | The Copilot CLI tool override path. When set, skips automatic download and uses the specified path. | ## Extension Configuration @@ -128,7 +130,7 @@ specific version of the tool installed on the machine. | --- | --- | | `AZD_UI_PROMPT_ENDPOINT` | The endpoint for external UI prompt service integration. | | `AZD_UI_PROMPT_KEY` | The authentication key for the external UI prompt service. | -| `AZD_UI_NO_PROMPT_DIALOG` | If true, disables prompt dialog UI. | +| `AZD_UI_NO_PROMPT_DIALOG` | Set to any non-empty value to disable prompt dialog UI. | ## Telemetry & Tracing @@ -198,7 +200,7 @@ These variables are used by the Terraform provider integration to authenticate w | Variable | Description | | --- | --- | | `NO_COLOR` | If set, disables color output. See [no-color.org](https://no-color.org). | -| `FORCE_COLOR` | If set, forces color output regardless of terminal detection. | +| `FORCE_COLOR` | Set to `1` to force color output regardless of terminal detection. Only the exact value `1` is recognized. | | `COLUMNS` | Overrides the detected terminal width (in columns). | | `TERM` | The terminal type. Used to detect terminal capabilities. | | `BROWSER` | The browser command to use for opening URLs (e.g., during `azd auth login`). |