Add rationale comments to production osgetenvlibrary suppressions

pkg/cli/add_interactive_orchestrator.go

@@ -71,15 +71,15 @@ func RunAddInteractive(ctx context.Context, config *AddInteractiveConfig) error
 	addInteractiveLog.Print("Starting interactive add workflow")
 
 	// Assert this function is not running in automated unit tests or CI
-	if os.Getenv("GO_TEST_MODE") == "true" || os.Getenv("CI") != "" { //nolint:osgetenvlibrary
+	if os.Getenv("GO_TEST_MODE") == "true" || os.Getenv("CI") != "" { //nolint:osgetenvlibrary // interactive guards intentionally honor test and CI process-env markers.
 		return errors.New("interactive add cannot be used in automated tests or CI environments")
 	}
 
 	// Set context on the config
 	config.Ctx = ctx
 
 	// Auto-detect GHES host from git remote if not already set
-	if os.Getenv("GH_HOST") == "" { //nolint:osgetenvlibrary
+	if os.Getenv("GH_HOST") == "" { //nolint:osgetenvlibrary // auto-detection only applies when the gh CLI host env is absent.
 		detectedHost := getHostFromOriginRemote()
 		if detectedHost != "github.com" {
 			addInteractiveLog.Printf("Auto-detected GHES host from git remote: %s", detectedHost)

pkg/cli/add_interactive_workflow.go

@@ -87,7 +87,7 @@ func (c *AddInteractiveConfig) checkStatusAndOfferRun(ctx context.Context) error
 	}
 
 	// In Codespaces, don't offer to trigger - provide link to Actions page instead
-	if os.Getenv("CODESPACES") == "true" { //nolint:osgetenvlibrary
+	if os.Getenv("CODESPACES") == "true" { //nolint:osgetenvlibrary // Codespaces UX detection intentionally uses GitHub's runtime env marker.
 		addInteractiveLog.Print("Running in Codespaces, skipping run offer and showing Actions link")
 		fmt.Fprintln(os.Stderr, "")
 		fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Running in GitHub Codespaces - please trigger the workflow manually from the Actions page"))

pkg/cli/add_wizard_command.go

@@ -84,7 +84,7 @@ Note: To create a new workflow from scratch, use the 'new' command instead.`,
 
 			// add-wizard requires an interactive terminal
 			isTerminal := tty.IsStdoutTerminal()
-			isCIEnv := os.Getenv("CI") != "" //nolint:osgetenvlibrary
+			isCIEnv := os.Getenv("CI") != "" //nolint:osgetenvlibrary // wizard interactivity intentionally checks the standard CI environment marker.
 			addWizardLog.Printf("Terminal check: is_terminal=%v, is_ci=%v", isTerminal, isCIEnv)
 			if !isTerminal || isCIEnv {
 				return errors.New("add-wizard requires an interactive terminal; use 'add' for non-interactive environments")

pkg/cli/ci.go

@@ -18,7 +18,7 @@ func IsRunningInCI() bool {
 	}
 
 	for _, v := range ciVars {
-		if os.Getenv(v) != "" { //nolint:osgetenvlibrary
+		if os.Getenv(v) != "" { //nolint:osgetenvlibrary // CI detection intentionally checks conventional process-env markers.
 			ciLog.Printf("CI environment detected via %s", v)
 			return true
 		}

pkg/cli/codespace.go

@@ -14,7 +14,7 @@ var codespaceLog = logger.New("cli:codespace")
 // by checking for the CODESPACES environment variable
 func isRunningInCodespace() bool {
 	// GitHub Codespaces sets CODESPACES=true environment variable
-	isCodespace := strings.EqualFold(os.Getenv("CODESPACES"), "true") //nolint:osgetenvlibrary
+	isCodespace := strings.EqualFold(os.Getenv("CODESPACES"), "true") //nolint:osgetenvlibrary // Codespaces detection intentionally uses GitHub's runtime env marker.
 	codespaceLog.Printf("Codespace detection: is_codespace=%v", isCodespace)
 	return isCodespace
 }

pkg/cli/compile_orchestrator.go

@@ -27,7 +27,7 @@ func CompileWorkflows(ctx context.Context, config CompileConfig) ([]*workflow.Wo
 	default:
 	}
 
-	if os.Getenv("GH_HOST") == "" { //nolint:osgetenvlibrary
+	if os.Getenv("GH_HOST") == "" { //nolint:osgetenvlibrary // auto-detection only applies when the gh CLI host env is absent.
 		if detectedHost := getHostFromOriginRemote(); detectedHost != "github.com" && detectedHost != "" {
 			compileOrchestratorLog.Printf("Auto-detected GHES host from git remote: %s", detectedHost)
 			workflow.SetDefaultGHHost(detectedHost)

pkg/cli/compile_update_check.go

@@ -108,7 +108,7 @@ func shouldRunCompileUpdateCheck(noCheckUpdate bool) bool {
 		compileUpdateCheckLog.Print("Update check disabled via --no-check-update flag")
 		return false
 	}
-	if os.Getenv(compileUpdateCheckDisableEnv) != "" { //nolint:osgetenvlibrary
+	if os.Getenv(compileUpdateCheckDisableEnv) != "" { //nolint:osgetenvlibrary // update checks intentionally support an env-based opt-out for automation.
 		compileUpdateCheckLog.Printf("Update check disabled via %s", compileUpdateCheckDisableEnv)
 		return false
 	}

pkg/cli/engine_secrets.go

@@ -231,11 +231,11 @@ func ensureSecretAvailable(req SecretRequirement, config EngineSecretConfig) err
 	}
 
 	// Check environment variable
-	envValue := os.Getenv(req.Name) //nolint:osgetenvlibrary
+	envValue := os.Getenv(req.Name) //nolint:osgetenvlibrary // secret setup intentionally checks inherited env values before prompting or uploading.
 	if envValue == "" {
 		// Check alternative environment variables
 		for _, alt := range req.AlternativeEnvVars {
-			envValue = os.Getenv(alt) //nolint:osgetenvlibrary
+			envValue = os.Getenv(alt) //nolint:osgetenvlibrary // secret setup intentionally checks inherited env aliases before prompting or uploading.
 			if envValue != "" {
 				engineSecretsLog.Printf("Found secret in alternative env var: %s", alt)
 				break
@@ -439,7 +439,7 @@ func checkOptionalSecret(req SecretRequirement, config EngineSecretConfig) error
 	}
 
 	// Check environment
-	if os.Getenv(req.Name) != "" { //nolint:osgetenvlibrary
+	if os.Getenv(req.Name) != "" { //nolint:osgetenvlibrary // optional secret discovery intentionally checks inherited env values.
 		if config.Verbose {
 			fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Optional secret %s found in environment", req.Name)))
 		}
@@ -552,11 +552,11 @@ func GetEngineSecretNameAndValue(engine string, existingSecrets map[string]struc
 		envVar = opt.EnvVarName
 	}
 
-	value := os.Getenv(envVar) //nolint:osgetenvlibrary
+	value := os.Getenv(envVar) //nolint:osgetenvlibrary // engine secret export intentionally reads inherited env values for upload.
 	if value == "" {
 		// Check alternative environment variables
 		for _, alt := range opt.AlternativeSecrets {
-			value = os.Getenv(alt) //nolint:osgetenvlibrary
+			value = os.Getenv(alt) //nolint:osgetenvlibrary // engine secret export intentionally reads inherited env aliases for upload.
 			if value != "" {
 				engineSecretsLog.Printf("Found secret in alternative env var: %s", alt)
 				break

pkg/cli/import_url_fetcher.go

@@ -305,7 +305,7 @@ func logResponseBodyVerbose(resp *http.Response) {
 }
 
 func importAuthGHHost() string {
-	ghHost := os.Getenv("GH_HOST") //nolint:osgetenvlibrary
+	ghHost := os.Getenv("GH_HOST") //nolint:osgetenvlibrary // import auth intentionally follows the gh CLI host environment.
 	if ghHost == "" {
 		return ""
 	}

pkg/cli/init.go

@@ -338,7 +338,7 @@ func isGHESHost(host string) bool {
 //  3. The hostname extracted from the git origin remote URL
 func detectGHESDeployment() string {
 	// Check GITHUB_SERVER_URL first (set inside GitHub Actions runners)
-	if serverURL := os.Getenv("GITHUB_SERVER_URL"); serverURL != "" { //nolint:osgetenvlibrary
+	if serverURL := os.Getenv("GITHUB_SERVER_URL"); serverURL != "" { //nolint:osgetenvlibrary // GHES detection intentionally trusts GitHub Actions server env hints.
 		// serverURL is like "https://ghes.example.com", extract just the host.
 		host := serverURL
 		for _, scheme := range []string{"https://", "http://"} {
@@ -352,7 +352,7 @@ func detectGHESDeployment() string {
 	}
 
 	// Check GH_HOST (set when using the gh CLI against an enterprise instance)
-	if ghHost := os.Getenv("GH_HOST"); ghHost != "" { //nolint:osgetenvlibrary
+	if ghHost := os.Getenv("GH_HOST"); ghHost != "" { //nolint:osgetenvlibrary // GHES detection intentionally honors the gh CLI host environment.
 		if isGHESHost(ghHost) {
 			initLog.Printf("Detected GHES deployment from GH_HOST: %s", ghHost)
 			return ghHost

pkg/cli/interactive.go

@@ -64,7 +64,7 @@ func CreateWorkflowInteractively(ctx context.Context, workflowName string, verbo
 	interactiveLog.Printf("Starting interactive workflow creation: workflowName=%s, force=%v", workflowName, force)
 
 	// Assert this function is not running in automated unit tests
-	if os.Getenv("GO_TEST_MODE") == "true" || os.Getenv("CI") != "" { //nolint:osgetenvlibrary
+	if os.Getenv("GO_TEST_MODE") == "true" || os.Getenv("CI") != "" { //nolint:osgetenvlibrary // interactive guards intentionally honor test and CI process-env markers.
 		return errors.New("interactive workflow creation cannot be used in automated tests or CI environments")
 	}
 

pkg/cli/logs_command.go

@@ -452,7 +452,7 @@ func repoIsLocal(repo string) bool {
 	ownerRepo, _ := repoutil.NormalizeRepoForAPI(repo)
 
 	// Fast path: GITHUB_REPOSITORY is always the current repo in MCP server containers.
-	if envRepo := os.Getenv("GITHUB_REPOSITORY"); envRepo != "" { //nolint:osgetenvlibrary
+	if envRepo := os.Getenv("GITHUB_REPOSITORY"); envRepo != "" { //nolint:osgetenvlibrary // MCP containers intentionally trust GitHub's repository env for fast-path matching.
 		return strings.EqualFold(ownerRepo, envRepo)
 	}
 

pkg/cli/mcp_repository.go

@@ -21,7 +21,7 @@ func getRepository(ctx context.Context) (string, error) {
 	}
 
 	// Try GITHUB_REPOSITORY environment variable first
-	repo := os.Getenv("GITHUB_REPOSITORY") //nolint:osgetenvlibrary
+	repo := os.Getenv("GITHUB_REPOSITORY") //nolint:osgetenvlibrary // MCP repository resolution intentionally prefers GitHub's runtime env.
 	if repo != "" {
 		mcpLog.Printf("Got repository from GITHUB_REPOSITORY: %s", repo)
 		mcpCache.SetRepo(repo)

pkg/cli/mcp_server_command.go

@@ -72,7 +72,7 @@ func runMCPServer(ctx context.Context, port int, cmdPath string, validateActor b
 	mcpServerEnv := withNonInteractiveCIEnv(nil)
 
 	// Get actor from environment variable
-	actor := os.Getenv("GITHUB_ACTOR") //nolint:osgetenvlibrary
+	actor := os.Getenv("GITHUB_ACTOR") //nolint:osgetenvlibrary // actor validation intentionally uses the GitHub Actions runtime environment.
 
 	if validateActor {
 		mcpLog.Printf("Actor validation enabled (--validate-actor flag)")

pkg/cli/mcp_tools_privileged.go

@@ -28,7 +28,7 @@ const (
 // GITHUB_REPOSITORY is forwarded to the agentic-workflows MCP server container via
 // env_vars in the MCP configuration and inherited by spawned subprocesses.
 func appendRepoFlagFromEnv(args []string) []string {
-	if repo := os.Getenv("GITHUB_REPOSITORY"); repo != "" { //nolint:osgetenvlibrary
+	if repo := os.Getenv("GITHUB_REPOSITORY"); repo != "" { //nolint:osgetenvlibrary // privileged MCP tools intentionally inherit the GitHub repository env.
 		return append(args, "--repo", repo)
 	}
 	return args

pkg/cli/mcp_validation.go

@@ -103,7 +103,7 @@ func validateServerSecrets(config parser.RegistryMCPServerConfig, verbose bool,
 				} else {
 					// Automatically try to get GitHub token for GitHub-related environment variables
 					if key == "GITHUB_PERSONAL_ACCESS_TOKEN" || key == "GITHUB_TOKEN" || key == "GH_TOKEN" {
-						if actualValue := os.Getenv(key); actualValue == "" { //nolint:osgetenvlibrary
+						if actualValue := os.Getenv(key); actualValue == "" { //nolint:osgetenvlibrary // validation intentionally checks the current process env before token fallback.
 							// Try to automatically get the GitHub token
 							if token, err := parser.GetGitHubToken(); err == nil {
 								config.Env[key] = token
@@ -114,7 +114,7 @@ func validateServerSecrets(config parser.RegistryMCPServerConfig, verbose bool,
 					} else {
 						// For backward compatibility: check if environment variable with this name exists
 						// This preserves the original behavior for existing tests
-						if actualValue := os.Getenv(key); actualValue == "" { //nolint:osgetenvlibrary
+						if actualValue := os.Getenv(key); actualValue == "" { //nolint:osgetenvlibrary // validation intentionally checks inherited env vars for backward compatibility.
 							return fmt.Errorf("environment variable '%s' not set", key)
 						}
 					}

pkg/cli/secret_set_command.go

@@ -162,7 +162,7 @@ func normalizeSecretSetAPIHost(apiBase string) string {
 
 func resolveSecretValueForSet(fromEnv, fromFlag string) (string, error) {
 	if fromEnv != "" {
-		v := os.Getenv(fromEnv) //nolint:osgetenvlibrary
+		v := os.Getenv(fromEnv) //nolint:osgetenvlibrary // --from-env intentionally copies a user-selected process-env secret.
 		if v == "" {
 			return "", fmt.Errorf("environment variable %s is not set or empty", fromEnv)
 		}

pkg/cli/secrets.go

@@ -103,7 +103,7 @@ func extractSecretsFromConfig(config parser.RegistryMCPServerConfig) []SecretInf
 func checkSecretsAvailability(secrets []SecretInfo, useActionsSecrets bool) []SecretInfo {
 	for i := range secrets {
 		// First check if it's in environment variables
-		if value := os.Getenv(secrets[i].Name); value != "" { //nolint:osgetenvlibrary
+		if value := os.Getenv(secrets[i].Name); value != "" { //nolint:osgetenvlibrary // secret discovery intentionally checks inherited env vars before prompting.
 			secrets[i].Available = true
 			secrets[i].Source = "env"
 			secrets[i].Value = value

pkg/cli/shell_completion.go

@@ -36,21 +36,21 @@ func DetectShell() ShellType {
 	shellCompletionLog.Print("Detecting current shell")
 
 	// Check shell-specific version variables first (most reliable)
-	if os.Getenv("ZSH_VERSION") != "" { //nolint:osgetenvlibrary
+	if os.Getenv("ZSH_VERSION") != "" { //nolint:osgetenvlibrary // shell detection intentionally relies on inherited shell marker env vars.
 		shellCompletionLog.Print("Detected zsh from ZSH_VERSION")
 		return ShellZsh
 	}
-	if os.Getenv("BASH_VERSION") != "" { //nolint:osgetenvlibrary
+	if os.Getenv("BASH_VERSION") != "" { //nolint:osgetenvlibrary // shell detection intentionally relies on inherited shell marker env vars.
 		shellCompletionLog.Print("Detected bash from BASH_VERSION")
 		return ShellBash
 	}
-	if os.Getenv("FISH_VERSION") != "" { //nolint:osgetenvlibrary
+	if os.Getenv("FISH_VERSION") != "" { //nolint:osgetenvlibrary // shell detection intentionally relies on inherited shell marker env vars.
 		shellCompletionLog.Print("Detected fish from FISH_VERSION")
 		return ShellFish
 	}
 
 	// Fall back to $SHELL environment variable
-	shell := os.Getenv("SHELL") //nolint:osgetenvlibrary
+	shell := os.Getenv("SHELL") //nolint:osgetenvlibrary // shell detection intentionally falls back to the user's SHELL environment.
 	if shell == "" {
 		shellCompletionLog.Print("SHELL environment variable not set, checking platform")
 		// On Windows, check for PowerShell
@@ -143,7 +143,7 @@ func installBashCompletion(verbose bool, cmd *cobra.Command) error {
 	// Try to determine the best location for bash completions
 	if runtime.GOOS == "darwin" {
 		// macOS with Homebrew
-		brewPrefix := os.Getenv("HOMEBREW_PREFIX") //nolint:osgetenvlibrary
+		brewPrefix := os.Getenv("HOMEBREW_PREFIX") //nolint:osgetenvlibrary // Homebrew installs intentionally honor explicit HOMEBREW_PREFIX overrides.
 		if brewPrefix == "" {
 			// Try common locations
 			for _, prefix := range []string{constants.HomebrewPrefix, constants.UsrLocalPrefix} {
@@ -425,7 +425,7 @@ func uninstallBashCompletion(verbose bool) error {
 
 	// macOS with Homebrew
 	if runtime.GOOS == "darwin" {
-		brewPrefix := os.Getenv("HOMEBREW_PREFIX") //nolint:osgetenvlibrary
+		brewPrefix := os.Getenv("HOMEBREW_PREFIX") //nolint:osgetenvlibrary // Homebrew installs intentionally honor explicit HOMEBREW_PREFIX overrides.
 		if brewPrefix == "" {
 			for _, prefix := range []string{constants.HomebrewPrefix, constants.UsrLocalPrefix} {
 				if fileutil.DirExists(filepath.Join(prefix, "etc", "bash_completion.d")) {

pkg/cli/update_check.go

@@ -74,7 +74,7 @@ func shouldCheckForUpdate(noCheckUpdate bool) bool {
 // This is a heuristic - we can't reliably detect this, so we're conservative
 func isRunningAsMCPServer() bool {
 	// Check for MCP_SERVER environment variable that could be set by the MCP server
-	return os.Getenv("GH_AW_MCP_SERVER") != "" //nolint:osgetenvlibrary
+	return os.Getenv("GH_AW_MCP_SERVER") != "" //nolint:osgetenvlibrary // MCP mode detection intentionally uses a dedicated process-env marker.
 }
 
 var (

pkg/console/accessibility.go

@@ -13,7 +13,7 @@ import "os"
 // - Simplify interactive elements
 // - Use plain text instead of fancy formatting
 func IsAccessibleMode() bool {
-	return os.Getenv("ACCESSIBLE") != "" || //nolint:osgetenvlibrary
-		os.Getenv("TERM") == "dumb" || //nolint:osgetenvlibrary
-		os.Getenv("NO_COLOR") != "" //nolint:osgetenvlibrary
+	return os.Getenv("ACCESSIBLE") != "" || //nolint:osgetenvlibrary // terminal accessibility flags are intentionally inherited from the process environment.
+		os.Getenv("TERM") == "dumb" || //nolint:osgetenvlibrary // terminal accessibility flags are intentionally inherited from the process environment.
+		os.Getenv("NO_COLOR") != "" //nolint:osgetenvlibrary // terminal accessibility flags are intentionally inherited from the process environment.
 }

pkg/constants/constants.go

@@ -569,7 +569,7 @@ const UsrLocalPrefix = "/usr/local"
 // Always uses forward slashes, which are required for git/GitHub paths.
 // GH_AW_WORKFLOWS_DIR overrides the default; any OS-specific separators are normalized.
 func GetWorkflowDir() string {
-	if dir := os.Getenv("GH_AW_WORKFLOWS_DIR"); dir != "" { //nolint:osgetenvlibrary
+	if dir := os.Getenv("GH_AW_WORKFLOWS_DIR"); dir != "" { //nolint:osgetenvlibrary // workflow directory overrides are intentionally process-env driven.
 		return filepath.ToSlash(dir)
 	}
 	return WorkflowsDir

pkg/envutil/envutil.go

@@ -36,7 +36,7 @@ func GetIntFromEnv(envVar string, defaultValue, minValue, maxValue int, debugLog
 		}
 	}
 
-	envValue := os.Getenv(envVar) //nolint:osgetenvlibrary
+	envValue := os.Getenv(envVar) //nolint:osgetenvlibrary // envutil centralizes audited process-env reads for downstream callers.
 	if envValue == "" {
 		return defaultValue
 	}

pkg/github/label_objective_mapping.go

@@ -149,7 +149,7 @@ func LoadObjectiveMappingFromConfig() *ObjectiveMapping {
 	labelObjectiveMappingLog.Print("Loading objective mapping configuration")
 
 	// Try loading from OBJECTIVE_MAPPING_JSON env var
-	if mappingJSON := os.Getenv("OBJECTIVE_MAPPING_JSON"); mappingJSON != "" { //nolint:osgetenvlibrary
+	if mappingJSON := os.Getenv("OBJECTIVE_MAPPING_JSON"); mappingJSON != "" { //nolint:osgetenvlibrary // objective mapping test and override payloads are intentionally injected via env.
 		labelObjectiveMappingLog.Print("Attempting to load from OBJECTIVE_MAPPING_JSON env var")
 		var om ObjectiveMapping
 		if err := json.Unmarshal([]byte(mappingJSON), &om); err == nil {

pkg/logger/logger.go

@@ -29,7 +29,7 @@ var (
 	debugEnv = initDebugEnv()
 
 	// DEBUG_COLORS environment variable to control color output.
-	debugColors = os.Getenv("DEBUG_COLORS") != "0" //nolint:osgetenvlibrary
+	debugColors = os.Getenv("DEBUG_COLORS") != "0" //nolint:osgetenvlibrary // logger debug color toggles intentionally follow process-wide env switches.
 
 	basePaletteColors = []color.Color{
 		styles.ColorInfo,
@@ -60,10 +60,10 @@ func buildColorPalette() []lipgloss.Style {
 // If DEBUG is set, it takes precedence. Otherwise, if ACTIONS_RUNNER_DEBUG=true,
 // all loggers are enabled (equivalent to DEBUG=*).
 func initDebugEnv() string {
-	if d := os.Getenv("DEBUG"); d != "" { //nolint:osgetenvlibrary
+	if d := os.Getenv("DEBUG"); d != "" { //nolint:osgetenvlibrary // logger debug selectors intentionally come from standard DEBUG env configuration.
 		return d
 	}
-	if os.Getenv("ACTIONS_RUNNER_DEBUG") == "true" { //nolint:osgetenvlibrary
+	if os.Getenv("ACTIONS_RUNNER_DEBUG") == "true" { //nolint:osgetenvlibrary // GitHub Actions runner debug mode is intentionally inherited from the job environment.
 		return "*"
 	}
 	return ""