From 4f1b1b12e3be4464b614a1d3cb3e73c450d47bc7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 17 Dec 2025 21:40:26 +0000 Subject: [PATCH 1/3] Initial plan From 2b38220e93facd1e62314ff5dd839b54987e79dd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 17 Dec 2025 21:51:15 +0000 Subject: [PATCH 2/3] Document comprehensive list of azd environment variables - Expand environment-variables.md from 21 to 119 lines with comprehensive documentation - Organize variables by category: Configuration, Authentication, Azure Resources, Platform, Container/Build, Tool Paths, Terminal/Output, Alpha Features, CI/CD Integration, Extensions, Cloud Shell, Debug/Development - Document 50+ environment variables including: * User-facing variables (AZURE_DEV_COLLECT_TELEMETRY, AZURE_DEV_USER_AGENT, AZURE_ENV_NAME, etc.) * Azure resource variables (AZURE_LOCATION, AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, etc.) * CI/CD integration variables (GITHUB_ACTIONS, TF_BUILD, SYSTEM_ACCESSTOKEN, ARM_* for Terraform) * Debug variables (AZD_DEBUG_*) * Extension variables (AZD_EXT_DEBUG, AZD_EXT_TIMEOUT, AZD_SERVER, AZD_ACCESS_TOKEN) * Output control variables (NO_COLOR, FORCE_COLOR, COLUMNS, BROWSER) - Add descriptions, usage context, and notes about deprecation where applicable - Add cspell dictionary entries for new technical terms Co-authored-by: kristenwomack <5034778+kristenwomack@users.noreply.github.com> --- cli/azd/.vscode/cspell-azd-dictionary.txt | 6 ++ cli/azd/.vscode/cspell.yaml | 20 ++++ cli/azd/docs/environment-variables.md | 120 ++++++++++++++++++++-- 3 files changed, 135 insertions(+), 11 deletions(-) diff --git a/cli/azd/.vscode/cspell-azd-dictionary.txt b/cli/azd/.vscode/cspell-azd-dictionary.txt index 185cd456b19..7291f5e451a 100644 --- a/cli/azd/.vscode/cspell-azd-dictionary.txt +++ b/cli/azd/.vscode/cspell-azd-dictionary.txt @@ -63,6 +63,7 @@ AZURESUBSCRIPTION azuretools azureutil azureyaml +AZURETENANT Backticks bicepparam bicept @@ -71,12 +72,14 @@ BOOLSLICE buildargs BUILDID BUILDNUMBER +Buildpacks buildpacks byoi callstack cflags charmbracelet circleci +CLOUDSHELL cmdrecord cmdsubst Cobo @@ -259,11 +262,13 @@ teamcity testdata tmpl toplevel +APPHOST traceparent tracesdk tracestate tracetest trafficmanager +USERPROFILE Truef typeflag unhide @@ -282,6 +287,7 @@ vsrpc vuejs webappignore webfrontend +westus westus2 wireinject yacspin diff --git a/cli/azd/.vscode/cspell.yaml b/cli/azd/.vscode/cspell.yaml index 4721aa0864e..401c793b3fd 100644 --- a/cli/azd/.vscode/cspell.yaml +++ b/cli/azd/.vscode/cspell.yaml @@ -1,17 +1,24 @@ import: ../../../.vscode/cspell.global.yaml words: + - ACCESSTOKEN + - APPHOST + - AZURESUBSCRIPTION - azcloud - azdext - azurefd - azcontainerregistry - backoff + - Buildpacks - Canonicalize - Chans - chinacloudapi + - CLOUDSHELL - Codespace - Codespaces - customtype + - devcenter - devcontainers + - eastus - errgroup - extendee - eiannone @@ -37,6 +44,7 @@ words: - unmarshals - unmarshaling - unsetting + - USERPROFILE - usgovcloudapi - jdbc - springframework @@ -45,6 +53,7 @@ words: - jsonschema - rustc - figspec + - westus languageSettings: - languageId: go ignoreRegExpList: @@ -243,6 +252,17 @@ overrides: - userosscache - docstates - dylib + - filename: "**/environment-variables.md" + words: + - USERPROFILE + - eastus + - westus + - devcenter + - Buildpacks + - ACCESSTOKEN + - AZURESUBSCRIPTION + - CLOUDSHELL + - APPHOST ignorePaths: - "**/*_test.go" - "**/mock*.go" diff --git a/cli/azd/docs/environment-variables.md b/cli/azd/docs/environment-variables.md index e96152a41be..cfa1a22909f 100644 --- a/cli/azd/docs/environment-variables.md +++ b/cli/azd/docs/environment-variables.md @@ -4,18 +4,116 @@ 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". -- `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. +## Configuration + +- `AZD_CONFIG_DIR`: The file path of the user-level configuration directory. Defaults to `~/.azd` on Linux/macOS and `%USERPROFILE%\.azd` on Windows. - `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_ALLOW_NON_EMPTY_FOLDER`: If true, allows `azd init` to initialize in a non-empty folder without prompting. + +## Authentication + +- `AZD_AUTH_ENDPOINT`: The [External Authentication](./external-authentication.md) endpoint URL for delegating authentication to an external service. +- `AZD_AUTH_KEY`: The [External Authentication](./external-authentication.md) shared key for authenticating with the external authentication service. +- `AZD_AUTH_CERT`: Certificate for external authentication. +- `AZURE_DEV_COLLECT_TELEMETRY`: Controls whether azd collects telemetry. Set to `no` to disable telemetry collection. This is the equivalent of `AZURE_CORE_COLLECT_TELEMETRY` used by other Azure SDKs. +- `AZURE_DEV_USER_AGENT`: User agent string that callers of azd (like VS Code extensions or Visual Studio) can set to identify themselves. Used for telemetry and diagnostics. + +## Azure Resources + +These environment variables are typically set automatically by azd in the environment's `.env` file after provisioning, but can also be set manually: + +- `AZURE_ENV_NAME`: The name of the azd environment. This is a required value for most azd operations. +- `AZURE_LOCATION`: The Azure region/location where resources are deployed (e.g., `eastus`, `westus2`). +- `AZURE_SUBSCRIPTION_ID`: The Azure subscription ID to use for deployment and resource management. +- `AZURE_TENANT_ID`: The Azure Active Directory tenant ID. +- `AZURE_PRINCIPAL_ID`: The ID of the identity (user or service principal) used for authentication. +- `AZURE_PRINCIPAL_TYPE`: The type of the principal (e.g., `User`, `ServicePrincipal`). +- `AZURE_RESOURCE_GROUP`: The name of the Azure resource group containing deployed resources. +- `AZURE_CONTAINER_REGISTRY_ENDPOINT`: The endpoint URL of the Azure Container Registry used for container image storage. +- `AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN`: The default domain for Azure Container Apps environments. +- `AZURE_AKS_CLUSTER_NAME`: The name of the Azure Kubernetes Service (AKS) cluster. +- `AZURE_APP_SERVICE_DASHBOARD_URI`: The URL for the App Service Aspire Dashboard. + +## Platform + +- `AZD_PLATFORM_TYPE`: Specifies the platform type being used (e.g., `devcenter` for Azure Deployment Environments). +- `AZD_INITIAL_ENVIRONMENT_CONFIG`: (Deprecated, but still supported) JSON string containing initial environment configuration. Used to reconstruct azd environment state in CI/CD pipelines. Prefer using individual variables or secrets for CI/CD parameters. -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: +## Container and Build + +- `AZD_BUILDER_IMAGE`: The Docker builder image to use for Dockerfile-less builds. Overrides the default builder image. + +## Tool Paths + +For tools that are auto-acquired by `azd`, you can configure the following environment variables to use a different 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_GH_TOOL_PATH`: The GitHub CLI (`gh`) tool override path. The direct path to `gh` or `gh.exe`. +- `AZD_PACK_TOOL_PATH`: The Cloud Native Buildpacks (`pack`) tool override path. The direct path to `pack` or `pack.exe`. + +## Terminal and Output Control + +- `AZD_FORCE_TTY`: If true, forces `azd` to write terminal-style output even when not running in an interactive terminal. +- `AZD_DEMO_MODE`: If true, enables demo mode. This hides personal information such as subscription IDs from being displayed in output. +- `NO_COLOR`: If set, disables colored output. This is a standard environment variable respected by many CLI tools. +- `FORCE_COLOR`: If set, forces colored output even when not running in an interactive terminal. +- `COLUMNS`: Specifies the console width in characters. Used for formatting output and markdown rendering. +- `TERM`: Terminal type identifier. Used to determine terminal capabilities. +- `BROWSER`: Specifies the browser command to use for opening URLs (e.g., when opening Azure Portal links). + +## Alpha Features + +- `AZD_ALPHA_ENABLE_`: Enables or disables an alpha feature. `` is the upper-cased name of the feature, with dot `.` characters replaced by underscore `_` characters. For example, to enable a feature named `awesome.feature`, set `AZD_ALPHA_ENABLE_AWESOME_FEATURE=true`. + +## CI/CD Integration + +### CI/CD Detection + +azd automatically detects when running in various CI/CD environments by checking for the following environment variables: + +- `GITHUB_ACTIONS`: Set to `true` by GitHub Actions. +- `TF_BUILD`: Set to `true` by Azure Pipelines. +- `CI`: Generic CI detection variable used by multiple CI systems. +- `CODESPACES`: Set when running in GitHub Codespaces. + +### Azure Pipelines + +When using Azure Pipelines with azd, the following variables are used for OIDC authentication: + +- `SYSTEM_ACCESSTOKEN`: The Azure Pipelines system access token. Must be explicitly mapped in the pipeline task configuration by adding `SYSTEM_ACCESSTOKEN: $(System.AccessToken)` to the `env` section. +- `AZURESUBSCRIPTION_CLIENT_ID`: The client ID for the Azure service connection. +- `AZURESUBSCRIPTION_TENANT_ID`: The tenant ID for the Azure service connection. +- `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID`: The Azure Pipelines service connection ID. + +### Terraform + +When using Terraform as the infrastructure provider, these environment variables are used for service principal authentication: + +- `ARM_CLIENT_ID`: The Azure service principal client ID. +- `ARM_CLIENT_SECRET`: The Azure service principal client secret. +- `ARM_TENANT_ID`: The Azure service principal tenant ID. + +## Extensions + +- `AZD_EXT_DEBUG`: If true, enables debug logging for azd extensions. +- `AZD_EXT_TIMEOUT`: Overrides the default timeout for extension operations (in seconds). +- `AZD_SERVER`: Specifies the server address for azd extensions to connect to. +- `AZD_ACCESS_TOKEN`: Access token used for authentication between azd extensions and the core azd process. + +## Cloud Shell + +- `AZD_IN_CLOUDSHELL`: If true, indicates that `azd` is running in Azure Cloud Shell. This enables Cloud Shell-specific behaviors and optimizations. + +## Debug and Development + +These environment variables are primarily intended for azd developers and advanced troubleshooting. They are not typically needed for normal azd usage. + +- `AZD_DEBUG_LOG`: If set, enables debug-level logging to help troubleshoot issues. +- `AZD_DEBUG_DOTNET_APPHOST_IGNORE_UNSUPPORTED_RESOURCES`: If true, ignores unsupported resources when working with .NET Aspire AppHost projects. +- `AZD_DEBUG_DOTNET_APPHOST_USE_FIXED_MANIFEST`: If true, uses a fixed manifest for .NET Aspire AppHost for testing purposes. +- `AZD_DEBUG_EXPERIMENTATION_TAS_ENDPOINT`: Overrides the default experimentation service endpoint for A/B testing features. +- `AZD_DEBUG_LOGIN_FORCE_SUBSCRIPTION_REFRESH`: If true, forces a refresh of the subscription list during login. +- `AZD_DEBUG_NO_ALPHA_WARNINGS`: If true, suppresses warnings about alpha features. +- `AZD_DEBUG_PROVISION_PROGRESS_DISABLE`: If true, disables the live progress display during infrastructure provisioning. +- `AZD_DEBUG_SERVER_DEBUG_ENDPOINTS`: If true, enables debug endpoints in the azd server. +- `AZD_DEBUG_SYNTHETIC_SUBSCRIPTION`: Specifies a synthetic subscription ID for testing purposes. From 0e4ee4c77b3a85e4d73f1571f9b23d4ffa4296de Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 7 Jan 2026 12:50:51 +0000 Subject: [PATCH 3/3] Update environment variables documentation with latest changes - Add AZURE_RESOURCE_VAULT_ID for Key Vault composability support - Sync documentation with main branch changes - Update to reflect all environment variables in current codebase Co-authored-by: spboyer <7681382+spboyer@users.noreply.github.com> --- cli/azd/docs/environment-variables.md | 1 + 1 file changed, 1 insertion(+) diff --git a/cli/azd/docs/environment-variables.md b/cli/azd/docs/environment-variables.md index cfa1a22909f..1a55b65e1ea 100644 --- a/cli/azd/docs/environment-variables.md +++ b/cli/azd/docs/environment-variables.md @@ -29,6 +29,7 @@ These environment variables are typically set automatically by azd in the enviro - `AZURE_PRINCIPAL_ID`: The ID of the identity (user or service principal) used for authentication. - `AZURE_PRINCIPAL_TYPE`: The type of the principal (e.g., `User`, `ServicePrincipal`). - `AZURE_RESOURCE_GROUP`: The name of the Azure resource group containing deployed resources. +- `AZURE_RESOURCE_VAULT_ID`: The Azure resource ID of the Key Vault created by `azd add` for composability scenarios. Provides shortcuts for Key Vault operations. - `AZURE_CONTAINER_REGISTRY_ENDPOINT`: The endpoint URL of the Azure Container Registry used for container image storage. - `AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN`: The default domain for Azure Container Apps environments. - `AZURE_AKS_CLUSTER_NAME`: The name of the Azure Kubernetes Service (AKS) cluster.