feat: Add global env section to atmos.yaml

Add support for a root-level `env` section in atmos.yaml that applies
environment variables to all subprocesses spawned by Atmos.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: osterman

cmd/auth_exec.go

@@ -14,6 +14,7 @@ import (
 
 	errUtils "github.com/cloudposse/atmos/errors"
 	cfg "github.com/cloudposse/atmos/pkg/config"
+	envpkg "github.com/cloudposse/atmos/pkg/env"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/schema"
 )
@@ -106,8 +107,9 @@ func executeAuthExecCommandCore(cmd *cobra.Command, args []string) error {
 	}
 
 	// Prepare shell environment with file-based credentials.
-	// Start with current OS environment and let PrepareShellEnvironment configure auth.
-	envList, err := authManager.PrepareShellEnvironment(ctx, identityName, os.Environ())
+	// Start with current OS environment + global env from atmos.yaml and let PrepareShellEnvironment configure auth.
+	baseEnv := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.Env)
+	envList, err := authManager.PrepareShellEnvironment(ctx, identityName, baseEnv)
 	if err != nil {
 		return fmt.Errorf("failed to prepare command environment: %w", err)
 	}

cmd/cmd_utils.go

@@ -23,6 +23,7 @@ import (
 	"github.com/cloudposse/atmos/pkg/auth/credentials"
 	"github.com/cloudposse/atmos/pkg/auth/validation"
 	cfg "github.com/cloudposse/atmos/pkg/config"
+	envpkg "github.com/cloudposse/atmos/pkg/env"
 	l "github.com/cloudposse/atmos/pkg/list"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
@@ -462,8 +463,8 @@ func executeCustomCommand(
 
 		// Prepare ENV vars
 		// ENV var values support Go templates and have access to {{ .ComponentConfig.xxx.yyy.zzz }} Go template variables
-		// Start with current environment to inherit PATH and other variables.
-		env := os.Environ()
+		// Start with current environment + global env from atmos.yaml to inherit PATH and other variables.
+		env := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.Env)
 		for _, v := range commandConfig.Env {
 			key := strings.TrimSpace(v.Key)
 			value := v.Value
@@ -489,7 +490,7 @@ func executeCustomCommand(
 			}
 
 			// Add or update the environment variable in the env slice
-			env = u.UpdateEnvVar(env, key, value)
+			env = envpkg.UpdateEnvVar(env, key, value)
 		}
 
 		if len(commandConfig.Env) > 0 && commandConfig.Verbose {

internal/exec/shell_utils.go

@@ -16,6 +16,7 @@ import (
 	"github.com/spf13/viper"
 
 	errUtils "github.com/cloudposse/atmos/errors"
+	envpkg "github.com/cloudposse/atmos/pkg/env"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/schema"
@@ -49,7 +50,10 @@ func ExecuteShellCommand(
 	updatedEnv := append(env, fmt.Sprintf("ATMOS_SHLVL=%d", newShellLevel))
 
 	cmd := exec.Command(command, args...)
-	cmd.Env = append(os.Environ(), updatedEnv...)
+	// Build environment: os.Environ() + global env (atmos.yaml) + command-specific env.
+	// Global env has lowest priority after system env, command-specific env overrides both.
+	baseEnv := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.Env)
+	cmd.Env = append(baseEnv, updatedEnv...)
 	cmd.Dir = dir
 	cmd.Stdin = os.Stdin
 	cmd.Stdout = os.Stdout
@@ -110,7 +114,7 @@ func ExecuteShell(
 	command string,
 	name string,
 	dir string,
-	env []string,
+	envVars []string,
 	dryRun bool,
 ) error {
 	defer perf.Track(nil, "exec.ExecuteShell")()
@@ -126,8 +130,8 @@ func ExecuteShell(
 	// This matches the behavior before commit 9fd7d156a where the environment
 	// was merged rather than replaced.
 	mergedEnv := os.Environ()
-	for _, envVar := range env {
-		mergedEnv = u.UpdateEnvVar(mergedEnv, parseEnvVarKey(envVar), parseEnvVarValue(envVar))
+	for _, envVar := range envVars {
+		mergedEnv = envpkg.UpdateEnvVar(mergedEnv, parseEnvVarKey(envVar), parseEnvVarValue(envVar))
 	}
 
 	mergedEnv = append(mergedEnv, fmt.Sprintf("ATMOS_SHLVL=%d", newShellLevel))
@@ -243,8 +247,9 @@ func execTerraformShellCommand(
 
 	log.Debug("Setting the ENV vars in the shell")
 
-	// Merge env vars, ensuring componentEnvList takes precedence
-	mergedEnv := mergeEnvVars(componentEnvList)
+	// Merge env vars, ensuring componentEnvList takes precedence.
+	// Include global env from atmos.yaml (lowest priority after system env).
+	mergedEnv := mergeEnvVarsWithGlobal(componentEnvList, atmosConfig.Env)
 
 	// Transfer stdin, stdout, and stderr to the new process and also set the target directory for the shell to start in
 	pa := os.ProcAttr{
@@ -341,7 +346,8 @@ func ExecAuthShellCommand(
 	printShellEnterMessage(identityName, providerName)
 
 	// Merge env vars, ensuring authEnvList takes precedence.
-	mergedEnv := mergeEnvVarsSimple(authEnvList)
+	// Include global env from atmos.yaml (lowest priority after system env).
+	mergedEnv := mergeEnvVarsSimpleWithGlobal(authEnvList, atmosConfig.Env)
 
 	// Determine shell command and args.
 	shellCommand, shellCommandArgs := determineShell(shellOverride, shellArgs)
@@ -529,6 +535,52 @@ func mergeEnvVars(componentEnvList []string) []string {
 	return merged
 }
 
+// mergeEnvVarsWithGlobal is like mergeEnvVars but also includes global env from atmos.yaml.
+// Priority order: system env < global env (atmos.yaml) < component env.
+func mergeEnvVarsWithGlobal(componentEnvList []string, globalEnv map[string]string) []string {
+	envMap := make(map[string]string)
+
+	// Parse system environment variables.
+	for _, env := range os.Environ() {
+		if parts := strings.SplitN(env, "=", 2); len(parts) == 2 {
+			envMap[parts[0]] = parts[1]
+		}
+	}
+
+	// Apply global env from atmos.yaml (can override system env).
+	for k, v := range globalEnv {
+		envMap[k] = v
+	}
+
+	// Merge with new, Atmos defined environment variables (highest priority).
+	for _, env := range componentEnvList {
+		if parts := strings.SplitN(env, "=", 2); len(parts) == 2 {
+			// Special handling for Terraform CLI arguments environment variables.
+			if strings.HasPrefix(parts[0], "TF_CLI_ARGS_") {
+				// For TF_CLI_ARGS_* variables, we need to append new values to any existing values.
+				if existing, exists := envMap[parts[0]]; exists {
+					// Put the new, Atmos defined value first so it takes precedence.
+					envMap[parts[0]] = parts[1] + " " + existing
+				} else {
+					// No existing value, just set the new value.
+					envMap[parts[0]] = parts[1]
+				}
+			} else {
+				// For all other environment variables, just override any existing value.
+				envMap[parts[0]] = parts[1]
+			}
+		}
+	}
+
+	// Convert back to slice.
+	merged := make([]string, 0, len(envMap))
+	for k, v := range envMap {
+		log.Trace("Setting ENV var", "key", k, "value", v)
+		merged = append(merged, k+"="+v)
+	}
+	return merged
+}
+
 // mergeEnvVarsSimple adds a list of environment variables to the system environment variables without special handling.
 func mergeEnvVarsSimple(newEnvList []string) []string {
 	envMap := make(map[string]string)
@@ -556,6 +608,39 @@ func mergeEnvVarsSimple(newEnvList []string) []string {
 	return merged
 }
 
+// mergeEnvVarsSimpleWithGlobal is like mergeEnvVarsSimple but includes global env from atmos.yaml.
+// Priority order: system env < global env (atmos.yaml) < new env list.
+func mergeEnvVarsSimpleWithGlobal(newEnvList []string, globalEnv map[string]string) []string {
+	envMap := make(map[string]string)
+
+	// Parse system environment variables.
+	for _, env := range os.Environ() {
+		if parts := strings.SplitN(env, envVarSeparator, 2); len(parts) == 2 {
+			envMap[parts[0]] = parts[1]
+		}
+	}
+
+	// Apply global env from atmos.yaml (can override system env).
+	for k, v := range globalEnv {
+		envMap[k] = v
+	}
+
+	// Merge with new environment variables (override any existing).
+	for _, env := range newEnvList {
+		if parts := strings.SplitN(env, envVarSeparator, 2); len(parts) == 2 {
+			envMap[parts[0]] = parts[1]
+		}
+	}
+
+	// Convert back to slice.
+	merged := make([]string, 0, len(envMap))
+	for k, v := range envMap {
+		log.Trace("Setting ENV var", "key", k, "value", v)
+		merged = append(merged, k+envVarSeparator+v)
+	}
+	return merged
+}
+
 // printShellEnterMessage prints a user-facing message when entering an Atmos-managed shell.
 func printShellEnterMessage(identityName, providerName string) {
 	headerStyle := lipgloss.NewStyle().

internal/exec/shell_utils_test.go

@@ -460,8 +460,9 @@ func TestExecAuthShellCommand_ExitCodePropagation(t *testing.T) {
 			envVars := map[string]string{
 				"TEST_VAR": "test_value",
 			}
+			atmosConfig := &schema.AtmosConfiguration{}
 
-			err := ExecAuthShellCommand(nil, "test-identity", "test-provider", envVars, "/bin/sh", tt.shellArgs)
+			err := ExecAuthShellCommand(atmosConfig, "test-identity", "test-provider", envVars, "/bin/sh", tt.shellArgs)
 
 			if tt.expectedCode == 0 {
 				assert.NoError(t, err)

internal/exec/stack_processor_process_stacks.go

@@ -21,6 +21,19 @@ const (
 	errFormatWithFile = "%w in file '%s'"
 )
 
+// convertEnvMapStringToAny converts map[string]string to map[string]any.
+// This is needed because stack processing uses map[string]any for env sections.
+func convertEnvMapStringToAny(env map[string]string) map[string]any {
+	if env == nil {
+		return nil
+	}
+	result := make(map[string]any, len(env))
+	for k, v := range env {
+		result[k] = v
+	}
+	return result
+}
+
 // ProcessStackConfig processes a stack configuration.
 //
 //nolint:gocognit,nestif,revive,cyclop,funlen // Core stack processing logic with complex configuration handling.
@@ -198,7 +211,9 @@ func ProcessStackConfig(
 		}
 	}
 
-	globalAndTerraformEnv, err := m.Merge(atmosConfig, []map[string]any{globalEnvSection, terraformEnv})
+	// Include atmos.yaml global env as lowest priority in the merge chain.
+	atmosConfigEnv := convertEnvMapStringToAny(atmosConfig.Env)
+	globalAndTerraformEnv, err := m.Merge(atmosConfig, []map[string]any{atmosConfigEnv, globalEnvSection, terraformEnv})
 	if err != nil {
 		return nil, err
 	}
@@ -297,7 +312,8 @@ func ProcessStackConfig(
 		}
 	}
 
-	globalAndHelmfileEnv, err := m.Merge(atmosConfig, []map[string]any{globalEnvSection, helmfileEnv})
+	// Include atmos.yaml global env as lowest priority in the merge chain.
+	globalAndHelmfileEnv, err := m.Merge(atmosConfig, []map[string]any{atmosConfigEnv, globalEnvSection, helmfileEnv})
 	if err != nil {
 		return nil, err
 	}
@@ -353,7 +369,8 @@ func ProcessStackConfig(
 		}
 	}
 
-	globalAndPackerEnv, err := m.Merge(atmosConfig, []map[string]any{globalEnvSection, packerEnv})
+	// Include atmos.yaml global env as lowest priority in the merge chain.
+	globalAndPackerEnv, err := m.Merge(atmosConfig, []map[string]any{atmosConfigEnv, globalEnvSection, packerEnv})
 	if err != nil {
 		return nil, err
 	}

internal/exec/utils.go

@@ -17,6 +17,7 @@ import (
 	errUtils "github.com/cloudposse/atmos/errors"
 	auth "github.com/cloudposse/atmos/pkg/auth"
 	cfg "github.com/cloudposse/atmos/pkg/config"
+	"github.com/cloudposse/atmos/pkg/env"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/schema"
@@ -603,7 +604,7 @@ func ProcessStacks(
 	}
 
 	// Process the ENV variables from the `env` section.
-	configAndStacksInfo.ComponentEnvList = u.ConvertEnvVars(configAndStacksInfo.ComponentEnvSection)
+	configAndStacksInfo.ComponentEnvList = env.ConvertEnvVars(configAndStacksInfo.ComponentEnvSection)
 
 	// Process component metadata.
 	_, baseComponentName, _, componentIsEnabled, componentIsLocked := ProcessComponentMetadata(configAndStacksInfo.ComponentFromArg, configAndStacksInfo.ComponentSection)

internal/exec/validate_component.go

@@ -10,6 +10,7 @@ import (
 
 	errUtils "github.com/cloudposse/atmos/errors"
 	cfg "github.com/cloudposse/atmos/pkg/config"
+	"github.com/cloudposse/atmos/pkg/env"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/schema"
@@ -244,7 +245,7 @@ func validateComponentInternal(
 	var ok bool
 
 	// Add the process environment variables to the component section.
-	componentSection[cfg.ProcessEnvSectionName] = u.EnvironToMap()
+	componentSection[cfg.ProcessEnvSectionName] = env.EnvironToMap()
 
 	switch schemaType {
 	case "jsonschema":

internal/exec/workflow_utils.go

@@ -18,6 +18,7 @@ import (
 	"github.com/cloudposse/atmos/pkg/auth/credentials"
 	"github.com/cloudposse/atmos/pkg/auth/validation"
 	"github.com/cloudposse/atmos/pkg/config"
+	envpkg "github.com/cloudposse/atmos/pkg/env"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/retry"
@@ -159,7 +160,9 @@ func ExecuteWorkflow(
 			commandType = "atmos"
 		}
 
-		// Prepare environment variables if identity is specified for this step.
+		// Prepare environment variables: start with system env + global env from atmos.yaml.
+		// Global env has lowest priority and can be overridden by identity auth env vars.
+		baseEnv := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.Env)
 		var stepEnv []string
 		if stepIdentity != "" {
 			if authManager == nil {
@@ -185,16 +188,16 @@ func ExecuteWorkflow(
 			}
 
 			// Prepare shell environment with authentication credentials.
-			// Start with current OS environment and let PrepareShellEnvironment configure auth.
-			stepEnv, err = authManager.PrepareShellEnvironment(ctx, stepIdentity, os.Environ())
+			// Start with base environment (system + global) and let PrepareShellEnvironment configure auth.
+			stepEnv, err = authManager.PrepareShellEnvironment(ctx, stepIdentity, baseEnv)
 			if err != nil {
 				return fmt.Errorf("failed to prepare shell environment for identity %q in step %q: %w", stepIdentity, step.Name, err)
 			}
 
 			log.Debug("Prepared environment with identity", "identity", stepIdentity, "step", step.Name)
 		} else {
-			// No identity specified, use empty environment (subprocess inherits from parent).
-			stepEnv = []string{}
+			// No identity specified, use base environment (system + global env).
+			stepEnv = baseEnv
 		}
 
 		var err error