[repository-quality] Repository Quality Improvement Report - GH CLI Wrapper Context Propagation Gap (2026-07-31)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - GH CLI Wrapper Context Propagation Gap

Analysis Date: 2026-07-31
Focus Area: GH CLI Wrapper Context Propagation Gap
Strategy Type: Custom
Custom Area: Yes — a prior run ("Context Propagation & Process Cancellability", 2026-06-03/06-09) tackled bare exec.Command calls broadly, but a distinct, narrower gap remains specifically in pkg/workflow/github_cli.go's public gh CLI wrapper API. Context-aware variants (*Context suffix) were added, yet the original non-context wrappers were kept and are still the majority choice at call sites across pkg/cli, meaning long-running gh api/gh pr/gh repo subprocess calls in CLI commands (clone, fork, create PR, merge, secrets) still cannot be cancelled or bounded by a caller-supplied timeout/deadline.

Executive Summary

pkg/workflow/github_cli.go offers two parallel APIs for every gh CLI wrapper: a legacy signature (ExecGH, RunGH, RunGHCombined, RunGHWithHost) that hardcodes context.Background(), and a context-aware counterpart (ExecGHContext, RunGHContext, RunGHCombinedContext, RunGHContextWithHost) that accepts a caller context. Both are exported and undocumented as to which one is preferred, so new code keeps reaching for the shorter, non-context signature. Grep counts show the non-context variants still outnumber their context-aware siblings at call sites (ExecGH 30 vs ExecGHContext 20, RunGH 30 vs RunGHContext 17, RunGHCombined 17 vs RunGHCombinedContext 11, RunGHWithHost 8 vs RunGHContextWithHost only 1), meaning roughly 60% of gh subprocess invocations across pkg/cli are not cancellable or time-boxed.

This matters concretely for commands like pr_command.go's repo clone/fork/PR-create flows, trial_repository.go's repository create/delete, and engine_secrets.go's secret listing — all of which can hang indefinitely on network stalls with no way for an enclosing command (Ctrl-C, CLI-level timeout flag, or test harness deadline) to interrupt them. The fix is mechanical and low-risk: migrate call sites to the *Context variants using cmd.Context() (Cobra) or a bounded context.WithTimeout, then deprecate/remove the non-context wrappers to close the gap permanently rather than let it regrow.

Full Analysis Report

Focus Area: GH CLI Wrapper Context Propagation Gap

Current State Assessment

pkg/workflow/github_cli.go defines a dual API surface:

func ExecGH(args ...string) *exec.Cmd {
	return setupGHCommand(context.Background(), args...)
}
func ExecGHContext(ctx context.Context, args ...string) *exec.Cmd {
	return setupGHCommand(ctx, args...)
}

The same pattern repeats for RunGH/RunGHContext, RunGHCombined/RunGHCombinedContext, and RunGHWithHost/RunGHContextWithHost. Every non-context wrapper is a one-line pass-through to context.Background(), so migrating callers is mechanical (swap function name, thread an existing ctx from the surrounding Cobra command or caller).

Metrics Collected:

Metric	Value	Status
ExecGH vs ExecGHContext callsites	30 vs 20 (60% legacy)	⚠️
RunGH vs RunGHContext callsites	30 vs 17 (64% legacy)	⚠️
RunGHCombined vs RunGHCombinedContext callsites	17 vs 11 (61% legacy)	⚠️
RunGHWithHost vs RunGHContextWithHost callsites	8 vs 1 (89% legacy)	❌
Overall bare context.Background()/context.TODO() in prod code	65 occurrences	⚠️
Related linter (ctxbackground) exists and registered	Yes, in pkg/linters/spec_test.go	✅

Findings

Strengths

• The context-aware API already exists and is well-documented with usage examples in doc comments (github_cli.go lines ~110-232).
• A dedicated ctxbackground static analyzer already flags context.Background() inside functions that already receive a context, giving infrastructure to catch regressions.
• Cobra's cmd.Context() is readily available in every pkg/cli command, so migration requires no new plumbing — just passing it through.

Areas for Improvement

• ⚠️ High: RunGHWithHost (8 callsites, e.g. pr_command.go:771,793) has almost no context-aware adoption (1/9, 11%) despite being used for cross-host repo/PR operations against GHES/data-residency hosts, which are exactly the operations most likely to need timeouts.
• ⚠️ Medium: Frequently-hit hot paths (pr_command.go, trial_repository.go, add_interactive_git.go) mix context and non-context calls in the same file (e.g. pr_command.go calls both RunGH and would benefit from consistently threading ctx), making it unclear which pattern is "current" for new contributors.
• ⚠️ Medium: No deprecation marker (// Deprecated:) on the non-context wrappers, so nothing signals to authors that the context variant is preferred — the API surface silently invites the legacy call.
• i️ Low: RunGHInputContext has no non-context sibling, proving context-first design is already the intended pattern for newer additions — this should be retrofitted onto the older wrapper family.

Detailed Analysis

The root cause is API design: adding *Context variants alongside (rather than replacing) the originals avoided a breaking change but left a permanent temptation to use the shorter, no-context signature — which is exactly what happened. Because pkg/cli commands almost always have a cmd *cobra.Command in scope with a live cmd.Context(), there is no technical barrier to full migration; this is purely an adoption/enforcement gap. The ctxbackground linter, which would catch context.Background() calls inside a function already holding a context, doesn't fire on github_cli.go itself because the wrapper functions (ExecGH, RunGH, etc.) don't accept a context parameter — the linter is structurally blind to this specific class of API-level, rather than local, hardcoding. Closing this requires both call-site migration and either deprecating or removing the non-context wrappers so the gap cannot silently reopen.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Migrate pr_command.go gh CLI calls to context-aware wrappers

Priority: High
Estimated Effort: Medium
Focus Area: GH CLI Wrapper Context Propagation Gap

Description: pkg/cli/pr_command.go contains 15+ call sites using RunGH, ExecGH, and RunGHWithHost (lines 109, 118, 144, 152, 161, 178, 216, 265, 514, 611, 642, 673, 771, 793) for fork/clone/PR-create/PR-diff operations against GitHub. None of these can be cancelled if the enclosing Cobra command is interrupted. Migrate every call site to its *Context counterpart (RunGHContext, ExecGHContext, RunGHContextWithHost), threading cmd.Context() from the owning Cobra RunE function down to each call.

Acceptance Criteria:

• All workflow.RunGH(, workflow.ExecGH(, workflow.RunGHWithHost( calls in pkg/cli/pr_command.go replaced with their *Context equivalents, passing a real ctx (from cmd.Context() or a threaded parameter)
• No behavior change to spinner messages, error wrapping, or output capture
• Existing tests in pkg/cli/pr_command_test.go pass unchanged
• make fmt run after edits

Code Region: pkg/cli/pr_command.go (lines 109-793, all workflow.RunGH*/ExecGH* calls)

In pkg/cli/pr_command.go, replace all calls to workflow.RunGH(...), workflow.ExecGH(...), and workflow.RunGHWithHost(...) with their context-aware equivalents workflow.RunGHContext(ctx, ...), workflow.ExecGHContext(ctx, ...), and workflow.RunGHContextWithHost(ctx, ...) respectively. Thread a context.Context through the calling functions, sourcing it from the owning Cobra command's cmd.Context() where a *cobra.Command is available, or accepting a ctx context.Context parameter for helper functions that don't currently have one. Do not change spinner behavior, error handling, or output capture logic — only the context threading. Run `make fmt` and `go build ./...` after the change, and run the existing tests in pkg/cli/pr_command_test.go to confirm no regressions.

---

Task 2: Migrate trial_repository.go and add_interactive_git.go to context-aware gh wrappers

Priority: High
Estimated Effort: Medium
Focus Area: GH CLI Wrapper Context Propagation Gap

Description: pkg/cli/trial_repository.go (repo create/delete/discussions-enable, lines 83-210) and pkg/cli/add_interactive_git.go (branch lookup, PR merge/update, lines 207-326) exclusively use non-context RunGHCombined/ExecGH calls for potentially slow network operations (repo creation, PR merge). These are prime candidates for user-triggered cancellation (Ctrl-C during interactive trial setup) which currently cannot propagate.

Acceptance Criteria:

• All workflow.RunGHCombined(/workflow.ExecGH( calls in both files replaced with RunGHCombinedContext/ExecGHContext, with ctx threaded from the calling command
• Interactive trial/setup flows still show spinners correctly in TTY mode
• Existing tests pass; add a regression test verifying a cancelled context aborts an in-flight gh call if not already covered

Code Region: pkg/cli/trial_repository.go (lines 83-210), pkg/cli/add_interactive_git.go (lines 207-326)

In pkg/cli/trial_repository.go and pkg/cli/add_interactive_git.go, replace all workflow.RunGHCombined(...) and workflow.ExecGH(...) calls with workflow.RunGHCombinedContext(ctx, ...) and workflow.ExecGHContext(ctx, ...), threading a context.Context from the enclosing Cobra command (cmd.Context()) or an existing ctx parameter down through each helper function. Verify spinner display in TTY mode is unaffected. If no existing test exercises context cancellation for these gh wrappers, add one unit test (in the corresponding _test.go file) that cancels a context before/during the call and asserts the command returns promptly with a context-cancellation-related error rather than hanging. Run `make fmt` after the change.

---

Task 3: Add // Deprecated: markers to non-context gh wrapper functions

Priority: Medium
Estimated Effort: Small
Focus Area: GH CLI Wrapper Context Propagation Gap

Description: To stop new code from reaching for the legacy signatures, mark ExecGH, RunGH, RunGHCombined, and RunGHWithHost in pkg/workflow/github_cli.go with standard Go // Deprecated: doc comments pointing to their *Context replacements. This makes staticcheck/IDE tooling surface a warning at every remaining and future call site without requiring an immediate breaking removal.

Acceptance Criteria:

• Each of the four legacy functions has a // Deprecated: use <XContext> instead, which accepts a context.Context for cancellation and timeout support. comment line
• go vet ./... / staticcheck (if configured) shows no new failures beyond the expected deprecation notices
• No functional/behavioral change — comment-only edit

Code Region: pkg/workflow/github_cli.go (functions ExecGH, RunGH, RunGHCombined, RunGHWithHost)

In pkg/workflow/github_cli.go, add a `// Deprecated:` line to the doc comments of ExecGH, RunGH, RunGHCombined, and RunGHWithHost, each pointing callers to its context-aware replacement (ExecGHContext, RunGHContext, RunGHCombinedContext, RunGHContextWithHost respectively). Follow standard Go deprecation comment convention (a paragraph starting with "Deprecated:" as its own sentence). Do not change any function behavior — this is a comment-only change. Run `make fmt` afterward and confirm `go build ./...` and `go vet ./...` still pass.

---

Task 4: Migrate remaining pkg/cli gh wrapper call sites (secrets, checks, enable, automerge, rate-limit)

Priority: Medium
Estimated Effort: Large
Focus Area: GH CLI Wrapper Context Propagation Gap

Description: Beyond the two hot files covered in Tasks 1-2, remaining legacy call sites exist in pkg/cli/add_interactive_secrets.go, pkg/cli/enable.go, pkg/cli/checks_command.go, pkg/cli/pr_automerge.go, pkg/cli/engine_secrets.go, pkg/cli/logs_rate_limit.go, and pkg/cli/outcome_eval_pr.go. These should be migrated in one sweep to fully close the adoption gap for all pkg/cli production code, bringing legacy usage to zero.

Acceptance Criteria:

• All remaining workflow.RunGH(/workflow.ExecGH(/workflow.RunGHCombined(/workflow.RunGHWithHost( calls in pkg/cli (excluding _test.go files) migrated to *Context equivalents
• grep -rn "workflow\.\(ExecGH\|RunGH\|RunGHCombined\|RunGHWithHost\)(" pkg/cli --include='*.go' | grep -v _test.go returns zero results after the change
• make agent-report-progress-no-test succeeds (build + lint pass)

Code Region: pkg/cli/add_interactive_secrets.go, pkg/cli/enable.go, pkg/cli/checks_command.go, pkg/cli/pr_automerge.go, pkg/cli/engine_secrets.go, pkg/cli/logs_rate_limit.go, pkg/cli/outcome_eval_pr.go

In the following files, replace every call to workflow.RunGH(...), workflow.ExecGH(...), workflow.RunGHCombined(...), and workflow.RunGHWithHost(...) with its context-aware counterpart (RunGHContext, ExecGHContext, RunGHCombinedContext, RunGHContextWithHost), threading a context.Context from the enclosing Cobra command's cmd.Context() or an existing ctx parameter:
- pkg/cli/add_interactive_secrets.go
- pkg/cli/enable.go
- pkg/cli/checks_command.go
- pkg/cli/pr_automerge.go
- pkg/cli/engine_secrets.go
- pkg/cli/logs_rate_limit.go
- pkg/cli/outcome_eval_pr.go

After migrating, verify with: `grep -rn "workflow\.\(ExecGH\|RunGH\|RunGHCombined\|RunGHWithHost\)(" pkg/cli --include='*.go' | grep -v _test.go` returns no results (excluding calls already using the *Context variants). Run `make fmt` and `make agent-report-progress-no-test` to confirm the build and fast checks pass. Do not modify test files' usage of these helpers unless it's trivial to also pass a context (e.g. context.Background() explicitly in tests is acceptable and out of scope).

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-07-17	Error Chain Transparency & Non-Wrapping fmt.Errorf Gap	Custom	Y	Identified fmt.Errorf calls losing %w wrapping
2026-07-22	Output Stream Abstraction Gap — Hardcoded os.Stdout	Custom	Y	Found render functions bypassing injectable writers
2026-07-28	CLI Flag Boilerplate Duplication & Legacy-Alias Drift	Custom	Y	Duplicated flag-registration logic across 5 files
2026-07-29	Panic Usage in Library Code — Linter Enforcement Gap	Custom	Y	sync.OnceValue panic blind spot in linter contract
2026-07-30	Test Parallelism Adoption Gap	Custom	Y	Only 2.7% of test functions use t.Parallel()
2026-07-31	GH CLI Wrapper Context Propagation Gap	Custom	Y	60-89% of gh CLI wrapper callsites still non-context-aware

---

🎯 Recommendations

Immediate Actions (This Week)

1. Migrate pr_command.go and trial_repository.go/add_interactive_git.go gh wrapper call sites to *Context variants (Tasks 1-2) — Priority: High

Short-term Actions (This Month)

1. Add // Deprecated: markers to legacy non-context wrappers (Task 3) — Priority: Medium
2. Sweep remaining pkg/cli call sites for full adoption (Task 4) — Priority: Medium

Long-term Actions (This Quarter)

1. Once adoption reaches 100%, remove the non-context wrapper functions entirely (breaking change, coordinate with a major version bump) — Priority: Low
2. Extend the ctxbackground linter (or add a new analyzer) to flag exported functions whose only purpose is to call an internal *Context sibling with context.Background(), catching this API-design anti-pattern automatically in future code — Priority: Low

---

📈 Success Metrics

• ExecGH/ExecGHContext adoption ratio: 40% context-aware → 100% context-aware
• RunGHWithHost/RunGHContextWithHost adoption ratio: 11% context-aware → 100% context-aware
• Legacy gh-wrapper call sites in pkg/cli (non-test): ~65 → 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 4-6 weeks to confirm adoption reached 100%

---

Generated by Repository Quality Improvement Agent
Next analysis: 2026-08-01 — Focus area selected by diversity algorithm

Generated by ⚡ Repository Quality Improvement Agent · auto · 46.5 AIC · ⌖ 8.13 AIC · ⊞ 9.5K · ◷

• expires on Aug 1, 2026, 5:27 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-01T13:27:17.699Z.

Closed by Workflow