[repository-quality] Repository Quality Improvement Report — 2026-07-07: Environment Variable Access Fragmentation

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Environment Variable Access Fragmentation

Analysis Date: 2026-07-07
Focus Area: Environment Variable Access Fragmentation — Missing envutil Boolean/String Helpers & Raw String Duplication
Strategy Type: Custom
Custom Area: Yes — envutil is an established but under-extended package; 45 bare suppressions with zero rationale, 6 env vars duplicated across multiple files, and existing helpers like IsRunningInCI() bypassed in 3 callsites show a systemic pattern.

Executive Summary

The pkg/envutil package was created to centralise environment variable access yet currently exposes only one helper: GetIntFromEnv. Meanwhile 45 production callsites carry //nolint:osgetenvlibrary suppressions with zero accompanying rationale comments, 24 distinct environment variable names are accessed via raw string literals, and 6 of those appear in 2–6 different source files. Two purpose-built wrappers (IsRunningInCI, isRunningInCodespace) already exist in pkg/cli but are bypassed by 3 and 1 callsites respectively within the same package.

The linter (osgetenvlibrary) was introduced to steer all env-var reads through envutil or equivalent centralised accessors, but the migration stalled after integer helpers were added. Boolean flags (CI, GO_TEST_MODE, CODESPACES), token-presence checks (GH_TOKEN, GITHUB_TOKEN), and frequently-repeated GitHub Actions env vars (GH_HOST, GITHUB_REPOSITORY, GITHUB_ACTOR) remain as duplicated raw lookups, making refactoring, mocking, and consistent behaviour across environments unnecessarily fragile.

The recommended path is to extend envutil with GetBoolFromEnv and GetStringFromEnv helpers, add named constants for the most-duplicated env vars, migrate the three os.Getenv("CI") bypasses to call IsRunningInCI(), and finally attach rationale comments to every surviving //nolint:osgetenvlibrary suppression so future reviewers can assess whether each exception is still warranted.

Full Analysis Report

Focus Area: Environment Variable Access Fragmentation

Current State Assessment

The pkg/envutil package was introduced to provide a single validated read path for environment variables, replacing scatter-shot os.Getenv calls in library code. However, the package has not grown beyond its initial GetIntFromEnv function, while the codebase has continued to accrue direct env-var reads.

Metrics Collected:

Metric	Value	Status
//nolint:osgetenvlibrary suppressions in production code	45	⚠️
Suppressions with a rationale comment	0 / 45	❌
Unique raw env-var string literals in production code	24	⚠️
Env vars duplicated across 2+ source files	6 (GH_HOST×6, GITHUB_REPOSITORY×3, CI×3, GO_TEST_MODE×2, CODESPACES×2, HOMEBREW_PREFIX×2)	⚠️
envutil helper functions	1 (GetIntFromEnv)	❌
Existing wrappers bypassed by same-package callers	2 (IsRunningInCI bypassed 3×; isRunningInCodespace bypassed 1×)	⚠️
Packages with direct env-var access	8 (pkg/cli×32, pkg/parser×3, pkg/logger×3, pkg/console×3, pkg/workflow×1, pkg/github×1, pkg/envutil×1, pkg/constants×1)	⚠️

Findings

Strengths

• pkg/envutil package exists and has a well-tested GetIntFromEnv helper with spec tests and README.
• IsRunningInCI() and isRunningInCodespace() wrappers already exist in pkg/cli, showing intent to centralise.
• The osgetenvlibrary linter actively enforces the constraint and catches new violations.
• pkg/workflow/process_env_lookup.go provides a single lookupProcessEnv wrapper for the workflow package.

Areas for Improvement

• No GetBoolFromEnv: All boolean env-var checks (CI != "", CODESPACES == "true", GO_TEST_MODE == "true") are duplicated raw.
• No GetStringFromEnv: Token reads (GH_TOKEN, GITHUB_TOKEN, GH_HOST) have no centralised, named accessor.
• Zero nolint rationale comments: 45 suppressions give no indication of why the direct read is acceptable, making auditing difficult.
• Same-package bypasses: add_interactive_orchestrator.go, add_wizard_command.go, and interactive.go call os.Getenv("CI") instead of IsRunningInCI(). add_interactive_workflow.go calls os.Getenv("CODESPACES") instead of isRunningInCodespace().
• GH_HOST constant missing: Used as a raw string in 6 files; no constants.EnvVarGHHost exists.

Detailed Analysis

Duplicated env var access by env var name:

Env Var	Files	Already has wrapper?
GH_HOST	github_cli.go, workflow_data.go, init.go, compile_orchestrator.go, add_interactive_orchestrator.go, import_url_fetcher.go	No
GITHUB_REPOSITORY	logs_command.go, mcp_repository.go, mcp_tools_privileged.go	No
CI	add_interactive_orchestrator.go, add_wizard_command.go, interactive.go	Yes — bypassed
GO_TEST_MODE	add_interactive_orchestrator.go, interactive.go	No
CODESPACES	add_interactive_workflow.go, codespace.go	Yes — bypassed
HOMEBREW_PREFIX	shell_completion.go (x2 in same file)	No

Raw boolean pattern examples:

// add_interactive_orchestrator.go:74
if os.Getenv("GO_TEST_MODE") == "true" || os.Getenv("CI") != "" { (nolint/redacted):osgetenvlibrary

// interactive.go:67
if os.Getenv("GO_TEST_MODE") == "true" || os.Getenv("CI") != "" { (nolint/redacted):osgetenvlibrary

Existing wrapper not used:

// ci.go (available)
func IsRunningInCI() bool { ... }

// add_wizard_command.go:87 (should use IsRunningInCI)
isCIEnv := os.Getenv("CI") != "" (nolint/redacted):osgetenvlibrary

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Migrate same-package CI and CODESPACES bypasses to existing wrappers

Priority: High
Estimated Effort: Small
Focus Area: Environment Variable Access Fragmentation

Description: Three files in pkg/cli call os.Getenv("CI") directly instead of using the existing IsRunningInCI() helper, and one file calls os.Getenv("CODESPACES") instead of isRunningInCodespace(). Migrate all four callsites to use the wrapper functions.

Acceptance Criteria:

• add_interactive_orchestrator.go:74 uses IsRunningInCI() instead of os.Getenv("CI")
• add_wizard_command.go:87 uses IsRunningInCI() instead of os.Getenv("CI")
• interactive.go:67 uses IsRunningInCI() instead of os.Getenv("CI")
• add_interactive_workflow.go:90 uses isRunningInCodespace() instead of os.Getenv("CODESPACES")
• All four //nolint:osgetenvlibrary suppressions removed (no longer needed after migration)
• make agent-report-progress passes

Code Region: pkg/cli/add_interactive_orchestrator.go, pkg/cli/add_wizard_command.go, pkg/cli/interactive.go, pkg/cli/add_interactive_workflow.go

In pkg/cli, replace the four direct os.Getenv calls that have existing wrappers:

1. pkg/cli/add_interactive_orchestrator.go line 74: replace os.Getenv("CI") with IsRunningInCI()
2. pkg/cli/add_wizard_command.go line 87: replace os.Getenv("CI") != "" with IsRunningInCI()
3. pkg/cli/interactive.go line 67: replace os.Getenv("CI") != "" with IsRunningInCI()
4. pkg/cli/add_interactive_workflow.go line 90: replace os.Getenv("CODESPACES") == "true" with isRunningInCodespace()

Remove the (nolint/redacted):osgetenvlibrary suppression from each migrated line.
Run make agent-report-progress to confirm the linter passes.

---

Task 2: Add GetBoolFromEnv helper to pkg/envutil and migrate GO_TEST_MODE callers

Priority: High
Estimated Effort: Medium
Focus Area: Environment Variable Access Fragmentation

Description: pkg/envutil lacks a boolean env-var helper. Add GetBoolFromEnv(envVar string) bool that returns true when the variable is set and has the value "true" (case-insensitive), false otherwise. Migrate the two GO_TEST_MODE raw reads to use it.

Acceptance Criteria:

• GetBoolFromEnv(envVar string) bool added to pkg/envutil/envutil.go with doc comment
• Package README.md updated with the new function's signature and contract
• spec_test.go extended with tests: returns false when unset, returns true for "true", returns true for "TRUE", returns false for "1", returns false for empty string
• add_interactive_orchestrator.go:74 and interactive.go:67 use the new helper for GO_TEST_MODE
• //nolint:osgetenvlibrary suppressions removed from migrated lines
• make agent-report-progress passes

Code Region: pkg/envutil/envutil.go, pkg/envutil/spec_test.go, pkg/envutil/README.md, pkg/cli/add_interactive_orchestrator.go, pkg/cli/interactive.go

1. In pkg/envutil/envutil.go add:
   // GetBoolFromEnv returns true if the named environment variable equals "true" (case-insensitive).
   func GetBoolFromEnv(envVar string) bool {
       return strings.EqualFold(os.Getenv(envVar), "true") (nolint/redacted):osgetenvlibrary // authorised raw read inside envutil
   }

2. Update pkg/envutil/README.md to document GetBoolFromEnv.

3. Add spec tests in pkg/envutil/spec_test.go.

4. In pkg/cli/add_interactive_orchestrator.go and pkg/cli/interactive.go replace
   os.Getenv("GO_TEST_MODE") == "true" with envutil.GetBoolFromEnv("GO_TEST_MODE").

5. Remove (nolint/redacted):osgetenvlibrary from the GO_TEST_MODE lines in both files.

Run make agent-report-progress.

---

Task 3: Add GH_HOST, GITHUB_REPOSITORY, GITHUB_ACTOR constants and migrate pkg/cli raw strings

Priority: Medium
Estimated Effort: Medium
Focus Area: Environment Variable Access Fragmentation

Description: GH_HOST is used as a raw string in 6 production files with no constant, GITHUB_REPOSITORY in 3 pkg/cli files, and GITHUB_ACTOR in 1. Add typed constants to pkg/constants and migrate the pkg/cli callsites to use them.

Acceptance Criteria:

• pkg/constants/ gains: EnvVarGHHost = "GH_HOST", EnvVarGitHubRepository = "GITHUB_REPOSITORY", EnvVarGitHubActor = "GITHUB_ACTOR", EnvVarGitHubServerURL = "GITHUB_SERVER_URL"
• pkg/constants/spec_test.go extended with contract tests for the new constants
• pkg/cli/init.go, pkg/cli/compile_orchestrator.go, pkg/cli/add_interactive_orchestrator.go, pkg/cli/import_url_fetcher.go replace "GH_HOST" with constants.EnvVarGHHost
• pkg/cli/logs_command.go, pkg/cli/mcp_repository.go, pkg/cli/mcp_tools_privileged.go replace "GITHUB_REPOSITORY" with constants.EnvVarGitHubRepository
• pkg/cli/mcp_server_command.go replaces "GITHUB_ACTOR" with constants.EnvVarGitHubActor
• make agent-report-progress passes

Code Region: pkg/constants/, pkg/cli/init.go, pkg/cli/compile_orchestrator.go, pkg/cli/add_interactive_orchestrator.go, pkg/cli/import_url_fetcher.go, pkg/cli/logs_command.go, pkg/cli/mcp_repository.go, pkg/cli/mcp_tools_privileged.go, pkg/cli/mcp_server_command.go

1. Add to pkg/constants/ (new file or existing file):
   const (
       EnvVarGHHost           = "GH_HOST"
       EnvVarGitHubRepository = "GITHUB_REPOSITORY"
       EnvVarGitHubActor      = "GITHUB_ACTOR"
       EnvVarGitHubServerURL  = "GITHUB_SERVER_URL"
   )

2. Add contract tests in pkg/constants/spec_test.go.

3. In pkg/cli, replace raw string literals with constants (GH_HOST in 4 files, GITHUB_REPOSITORY in 3 files, GITHUB_ACTOR in 1 file).

4. Do NOT modify pkg/workflow files — that is a separate task.

Run make agent-report-progress.

---

Task 4: Add rationale comments to all surviving nolint:osgetenvlibrary suppressions

Priority: Medium
Estimated Effort: Medium
Focus Area: Environment Variable Access Fragmentation

Description: After Tasks 1–3 reduce the suppression count, annotate every remaining //nolint:osgetenvlibrary in production code with a brief rationale comment explaining why the direct read is justified.

Acceptance Criteria:

• Every //nolint:osgetenvlibrary in pkg/ and cmd/ (excluding _test.go and testdata) has an inline rationale comment appended after the nolint directive
• No new bare suppressions are introduced
• make agent-report-progress passes

Code Region: All files under pkg/ and cmd/ containing //nolint:osgetenvlibrary

For every (nolint/redacted):osgetenvlibrary suppression in pkg/ and cmd/ (excluding _test.go and testdata),
add a brief rationale comment. Examples:

  pkg/logger/logger.go — reads DEBUG/ACTIONS_RUNNER_DEBUG at package-init time:
    (nolint/redacted):osgetenvlibrary // logger bootstrap: reads env before envutil is available

  pkg/console/accessibility.go — standard XDG/POSIX conventions:
    (nolint/redacted):osgetenvlibrary // XDG/POSIX convention; no gh-aw constant defined

  pkg/envutil/envutil.go — authorised raw read inside envutil:
    (nolint/redacted):osgetenvlibrary // authorised raw read inside envutil package

  pkg/workflow/process_env_lookup.go — authorised env adapter:
    (nolint/redacted):osgetenvlibrary // authorised env adapter for workflow package

Apply equivalent rationale comments to all remaining suppressions. Run make agent-report-progress.

---

Task 5: Add GetStringFromEnv helper to pkg/envutil for token/host env vars with fallback

Priority: Low
Estimated Effort: Medium
Focus Area: Environment Variable Access Fragmentation

Description: pkg/parser/github.go reads GITHUB_TOKEN then falls back to GH_TOKEN. Add GetStringFromEnv(envVar string, fallback ...string) string to pkg/envutil and migrate the token-fallback read.

Acceptance Criteria:

• GetStringFromEnv(envVar string, fallback ...string) string added to pkg/envutil/envutil.go
• Package README.md updated documenting GetStringFromEnv
• spec_test.go covers: primary set returns primary; primary empty + fallback set returns fallback; both empty returns ""; no fallback returns value or ""
• pkg/parser/github.go lines 65–69 use envutil.GetStringFromEnv("GITHUB_TOKEN", "GH_TOKEN")
• //nolint:osgetenvlibrary suppressions removed from migrated lines
• make agent-report-progress passes

Code Region: pkg/envutil/envutil.go, pkg/envutil/spec_test.go, pkg/envutil/README.md, pkg/parser/github.go

1. In pkg/envutil/envutil.go add:
   // GetStringFromEnv returns the value of the first env var in the list that is non-empty.
   func GetStringFromEnv(envVar string, fallback ...string) string {
       if v := os.Getenv(envVar); v != "" { (nolint/redacted):osgetenvlibrary // authorised raw read inside envutil
           return v
       }
       for _, alt := range fallback {
           if v := os.Getenv(alt); v != "" { (nolint/redacted):osgetenvlibrary // authorised raw read inside envutil
               return v
           }
       }
       return ""
   }

2. Update pkg/envutil/README.md.

3. Add spec tests in pkg/envutil/spec_test.go.

4. In pkg/parser/github.go, replace the GITHUB_TOKEN / GH_TOKEN pair with:
   if token := envutil.GetStringFromEnv("GITHUB_TOKEN", "GH_TOKEN"); token != "" { ... }

5. Remove the two (nolint/redacted):osgetenvlibrary suppressions.

Run make agent-report-progress.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-07-06	Context-Blind Sleep Gap	Custom	Y	4 functions / 7 time.Sleep calls; checkAndWaitForRateLimit blocks ~60 min
2026-07-03	ADR-42150 Implementation Gap	Custom	Y	yaml tag, registry key, error messages, samples_validation, test workflow
2026-07-02	Remote Fetch API Context Gap	Custom	Y	8 public parser wrappers strip caller context
2026-07-01	Codemod Registry Drift & Idempotency Coverage Gap	Custom	Y	20/62 codemod IDs absent from spec test
2026-06-30	Unauthenticated API Fallback Call Chain	Custom	Y	3 functions use http.DefaultClient (no timeout)

---

🎯 Recommendations

Immediate Actions (This Week)

1. Migrate 4 same-package bypasses to IsRunningInCI() / isRunningInCodespace() — Priority: High
2. Add GetBoolFromEnv and migrate GO_TEST_MODE reads — Priority: High

Short-term Actions (This Month)

1. Add GH_HOST, GITHUB_REPOSITORY, GITHUB_ACTOR constants and migrate pkg/cli — Priority: Medium
2. Add rationale comments to all surviving //nolint:osgetenvlibrary suppressions — Priority: Medium

Long-term Actions (This Quarter)

1. Add GetStringFromEnv with fallback support and migrate token pair reads — Priority: Low

---

📈 Success Metrics

• Bare nolint suppressions: 45 → 0 (all have rationale comments)
• Duplicated raw env-var strings (2+ files): 6 → 0
• envutil helper functions: 1 → 3 (GetIntFromEnv, GetBoolFromEnv, GetStringFromEnv)
• Same-package wrapper bypasses: 4 → 0

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate this focus area in 2 weeks

---

References:

• §28870016670

Generated by ⚡ Repository Quality Improvement Agent · 123.6 AIC · ⌖ 7.34 AIC · ⊞ 6.6K · ◷

• expires on Jul 8, 2026, 5:44 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-08T13:44:16.247Z.

Closed by Workflow