Document existing environment variables (#4321)

Document existing environment variables in a markdown file.

Contributes to #4320

.github/workflows/cli-ci.yml

@@ -4,7 +4,6 @@ on:
   pull_request:
     paths:
       - "cli/**"
-      - '!cli/docs/**'
       - ".github/workflows/cli-ci.yml"
       - "go.mod"
     branches: [main]
@@ -39,7 +38,7 @@ jobs:
         with:
           node-version: "20"
       - run: npm install -g cspell@8.13.1
-      - name: Spell check for CLI source code
+      - name: Spell check for go and docs
         run: cspell lint '**/*.{go,md}' --config ./cli/azd/.vscode/cspell.yaml --root ./cli/azd --no-progress
 
   bicep-lint:

cli/azd/docs/alpha-features.md

@@ -13,6 +13,10 @@ The strategy to ask `azd` to `toggle` between modes is:
 - Disable _all_ experimental features: `azd config unset alpha.all` or `azd config set alpha.all off`
 - Disable _specific_ experimental feature: `azd config unset alpha.featureName` or `azd config set alpha.featureName off`
 
+In CI, the on/off mode can be configured using environment variables with the following scheme:
+
+- `AZD_ALPHA_ENABLE_<name>`: where `<name>` is the upper-cased name of the feature, with dot `.` characters replaced by underscore `_` characters.
+
 ## Alpha feature
 
 All features start as alpha features (e.g., experimental). In this phase, the goal is to receive sufficient usage to get meaningful feedback around the feature’s design, functionality and user experience.

cli/azd/docs/environment-variables.md

@@ -0,0 +1,21 @@
+# Environment Variables
+
+## Environment variables used with 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".
+
+- `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.
+- `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.
+
+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:
+
+- `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`.

cli/azd/pkg/tools/github/github.go

@@ -49,7 +49,7 @@ func newGitHubCliImplementation(
 	acquireGitHubCliImpl getGitHubCliImplementation,
 	extractImplementation extractGitHubCliFromFileImplementation,
 ) (*Cli, error) {
-	if override := os.Getenv("AZD_GH_CLI_TOOL_PATH"); override != "" {
+	if override := os.Getenv("AZD_GH_TOOL_PATH"); override != "" {
 		log.Printf("using external github cli tool: %s", override)
 		cli := &Cli{
 			path:          override,

eng/pipelines/release-cli.yml

@@ -18,6 +18,8 @@ pr:
       - cli/
       - eng/pipelines/release-cli.yml
       - eng/pipelines/templates/steps/publish-cli.yml
+    exclude:
+      - cli/azd/docs/**
 
 extends: 
   template: /eng/pipelines/templates/stages/1es-redirect.yml