[go-fan] Go Module Review: github.com/cli/go-gh/v2

[github-actions[bot]]

🐹 Go Fan Report: github.com/cli/go-gh/v2

Module Overview

github.com/cli/go-gh/v2 is the official Go library for GitHub CLI, providing seamless GitHub API integration for CLI extensions and Go applications. It handles authentication automatically, respects GitHub CLI conventions, and provides utilities for terminal capabilities, repository context detection, and both REST and GraphQL API interactions.

Key Highlight: The project has been upgraded to v2.13.0 (from v2.12.2), which includes HTTP status 205 handling fixes, the new replace sprig function, and Go 1.25.0 support.

Current Usage in gh-aw

The project uses go-gh in 4 files with a total of approximately 850 lines of code leveraging this module:

• Files: 4 Go source files
• Import Count: 4 imports
• Key APIs Used: Exclusively gh.Exec() for shell-out commands

Usage Breakdown

1. pkg/workflow/repository_features_validation.go (182 lines)

   • Repository feature detection (discussions, issues)
   • GraphQL queries for discussions status
   • REST API calls for repository metadata
   • Caching with sync.Map for performance

2. pkg/workflow/github_cli.go (58 lines)

   • Wrapper functions ExecGH() and ExecGHWithOutput()
   • Token management (GH_TOKEN/GITHUB_TOKEN)
   • Backward compatibility layer

3. pkg/cli/exec.go (140 lines)

   • Conditional gh CLI usage with fallback
   • Git command inference for gh repo clone
   • Graceful degradation when GH_TOKEN unavailable

4. pkg/parser/remote_fetch.go (410 lines)

   • Remote workflow file downloads
   • API calls for file contents and ref resolution
   • Git fallback mechanisms for public repos

Current Usage Pattern

Shell-Out Approach (100% of usage):

// Current pattern
stdOut, _, err := gh.Exec("repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner")
stdOut, _, err := gh.Exec("api", "graphql", "-f", fmt.Sprintf("query=%s", query), ...)
stdOut, _, err := gh.Exec("api", fmt.Sprintf("repos/%s", repo))

No native REST/GraphQL client usage detected - all GitHub API interactions go through CLI shell-outs with manual JSON parsing.

Research Findings

What's New in v2.13.0

✨ Features:

• Exposed replace sprig function for Go template string manipulation
• Updated to Go 1.25.0 support

🐛 Fixes:

• Fixed HTTP status 205 handling properly
• Documented that HandleHTTPError does not close response body

🔒 Security Note:

• v2.12.1 fixed GHSA-g9f5-x53j-h563 (arbitrary command execution via malicious GitHub Enterprise Server URLs)

Best Practices from Upstream

The go-gh documentation and examples strongly recommend:

1. Use Native API Clients instead of shell-outs:

   // Recommended
   client, err := api.DefaultRESTClient()
   response := struct{ Name string }{}
   err = client.Get("repos/owner/repo", &response)

2. Use repository.Current() for automatic repo detection:

   // Recommended
   repo, err := repository.Current()
   // Instead of: gh.Exec("repo", "view", ...)

3. Enable API Caching for better performance:

   opts := api.ClientOptions{
       EnableCache: true,
       CacheTTL: 5 * time.Minute,
   }

4. Use GraphQL Client for complex queries:

   client, err := api.DefaultGraphQLClient()
   err = client.Query("MyQuery", &response, variables)

Improvement Opportunities

Full Improvement Analysis

🏃 Quick Wins (High Impact, Low Effort)

1. Replace gh repo view with repository.Current()

Location: pkg/workflow/repository_features_validation.go:182

Current:

stdOut, _, err := gh.Exec("repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner")
repo := strings.TrimSpace(stdOut.String())

Better:

repo, err := repository.Current()

Benefits:

• ✅ No shell-out overhead
• ✅ Cleaner, more readable code
• ✅ Better error messages
• ✅ Respects GH_REPO environment variable automatically

Estimated Effort: 5 minutes

---

2. Use api.DefaultRESTClient() for Repository Queries

Location: pkg/workflow/repository_features_validation.go:317

Current:

stdOut, _, err := gh.Exec("api", fmt.Sprintf("repos/%s", repo))
var response RepositoryResponse
if err := json.Unmarshal(stdOut.Bytes(), &response); err != nil {
    // handle error
}

Better:

client, err := api.DefaultRESTClient()
var response RepositoryResponse
err = client.Get(fmt.Sprintf("repos/%s", repo), &response)

Benefits:

• ✅ Type-safe, automatic JSON unmarshaling
• ✅ No manual JSON parsing needed
• ✅ Better performance (no process spawning)
• ✅ Built-in retry logic

Estimated Effort: 10 minutes

---

3. Use api.DefaultGraphQLClient() for Discussions Check

Location: pkg/workflow/repository_features_validation.go:286

Current:

stdOut, _, err := gh.Exec("api", "graphql", "-f", fmt.Sprintf("query=%s", query),
    "-f", fmt.Sprintf("owner=%s", owner), "-f", fmt.Sprintf("name=%s", name))
var response GraphQLResponse
if err := json.Unmarshal(stdOut.Bytes(), &response); err != nil {
    // handle error
}

Better:

client, err := api.DefaultGraphQLClient()
variables := map[string]interface{}{
    "owner": owner,
    "name":  name,
}
var response GraphQLResponse
err = client.Query("HasDiscussions", &response, variables)

Benefits:

• ✅ Type-safe variable handling
• ✅ Automatic query formatting
• ✅ Cleaner, more maintainable code
• ✅ Better error messages

Estimated Effort: 15 minutes

---

✨ Feature Opportunities

1. Enable API Caching for Repository Features

The code already implements application-level caching with sync.Map. Adding go-gh's built-in HTTP caching layer would provide additional benefits:

// Create cached REST client
opts := api.ClientOptions{
    EnableCache: true,
    CacheTTL:    5 * time.Minute,
}
client, err := api.NewRESTClient(opts)

Benefits:

• Reduces duplicate API calls across different parts of the codebase
• HTTP-level caching complements application-level caching
• Automatic cache invalidation based on TTL

Estimated Effort: 30 minutes

---

2. Leverage New replace Sprig Function (v2.13.0)

If the project uses Go templates for output formatting, the new replace function provides powerful string manipulation:

// Available in v2.13.0
{{ .name | replace "-" "_" }}

Action: Audit template usage and consider leveraging new sprig functions.

Estimated Effort: Variable (depending on template usage)

---

3. Consider Accessible Colors for Markdown Rendering

If rendering markdown to terminal, consider supporting GH_ACCESSIBLE_COLORS:

// Respects user's terminal color preferences
os.Setenv("GH_ACCESSIBLE_COLORS", "1")

Benefits:

• Better accessibility for users with vision impairments
• Respects terminal color customization
• Follows GitHub CLI conventions

Estimated Effort: 10 minutes

---

📐 Best Practice Alignment

1. Consolidate GitHub API Logic into Dedicated Package

Current State: GitHub API calls are scattered across:

• pkg/workflow/repository_features_validation.go
• pkg/workflow/github_cli.go
• pkg/cli/exec.go
• pkg/parser/remote_fetch.go

Recommended Structure:

pkg/github/
├── client.go          // Centralized REST/GraphQL client initialization
├── repository.go      // Repository operations (GetRepository, HasDiscussions, HasIssues)
├── contents.go        // File operations (GetFileContents, DownloadFile)
└── auth.go           // Token management using pkg/auth

Benefits:

• DRY principle - no duplicate API logic
• Easier testing with mock interfaces
• Consistent error handling
• Single source of truth for API configuration

Estimated Effort: 2-3 hours

---

2. Eliminate Manual Base64 Decoding

Location: pkg/parser/remote_fetch.go:401

Current:

stdOut, _, err := gh.Exec("api", fmt.Sprintf("/repos/%s/%s/contents/%s?ref=%s", ...))
contentBase64 := strings.TrimSpace(stdOut.String())
decodeCmd := exec.Command("base64", "-d")
decodeCmd.Stdin = strings.NewReader(contentBase64)
content, err := decodeCmd.Output()

Better:

client, err := api.DefaultRESTClient()
var fileContent struct {
    Content  string `json:"content"`
    Encoding string `json:"encoding"`
}
err = client.Get(fmt.Sprintf("repos/%s/%s/contents/%s?ref=%s", ...), &fileContent)
content, err := base64.StdEncoding.DecodeString(fileContent.Content)

Benefits:

• No shell dependency for base64 decoding
• Cross-platform compatibility
• Cleaner error handling
• Better performance

Estimated Effort: 20 minutes

---

3. Replace Error String Matching with Typed Errors

Current Pattern (multiple files):

if strings.Contains(err.Error(), "auth") || 
   strings.Contains(err.Error(), "unauthoriz") ||
   strings.Contains(err.Error(), "forbidden") {
    // handle auth error
}

Better:

// Use HTTP status codes or typed errors
var httpErr api.HTTPError
if errors.As(err, &httpErr) && (httpErr.StatusCode == 401 || httpErr.StatusCode == 403) {
    // handle auth error
}

Benefits:

• More reliable error detection
• Language-independent
• Better type safety
• Clearer intent

Estimated Effort: 1 hour

---

4. Adopt pkg/auth for Token Management

Location: pkg/workflow/github_cli.go:24-38

Current:

ghToken := os.Getenv("GH_TOKEN")
githubToken := os.Getenv("GITHUB_TOKEN")
if ghToken == "" && githubToken != "" {
    cmd.Env = append(os.Environ(), "GH_TOKEN="+githubToken)
}

Better:

import "github.com/cli/go-gh/v2/pkg/auth"

// Automatically handles GH_TOKEN, GITHUB_TOKEN, and OAuth tokens
token, _ := auth.TokenForHost("github.com")

Benefits:

• Consistent with GitHub CLI behavior
• Supports multiple auth methods (OAuth, token, etc.)
• Automatic host-specific token selection
• Respects gh configuration

Estimated Effort: 30 minutes

---

🔧 General Improvements

1. Migration Path from Shell-Outs to Native Clients

Recommended Approach:

1. Create abstraction layer (interface) that works with both approaches
2. Gradually migrate high-frequency operations first (repository features)
3. Use feature flag or environment variable to toggle implementations
4. Benchmark performance differences
5. Complete migration after validation

Example Interface:

type GitHubClient interface {
    GetRepository(repo string) (*Repository, error)
    HasDiscussions(repo string) (bool, error)
    HasIssues(repo string) (bool, error)
}

// Implementations: ShellOutClient, NativeClient

Benefits:

• Smooth transition with rollback capability
• A/B testing between approaches
• Gradual migration reduces risk
• Performance comparison data

Estimated Effort: 4-6 hours for full migration

---

2. Add HTTP Response Body Cleanup

Important Note: v2.13.0 documentation clarifies that HandleHTTPError does NOT close response bodies.

Action: Ensure response bodies are properly closed when using REST client:

resp, err := client.Get("repos/owner/repo", &result)
if resp != nil && resp.Body != nil {
    defer resp.Body.Close()
}

Estimated Effort: 15 minutes (code review)

---

3. Consider REST Client for File Downloads

Location: pkg/parser/remote_fetch.go:375-409

The current multi-step process with base64 decoding and git fallbacks could be simplified with native REST client usage.

Benefits:

• Simpler code flow
• Fewer error points
• Better performance
• Native content handling

Estimated Effort: 1 hour

Recommendations

Priority 1: High-Impact, Low-Effort (Start Here! 🎯)

1. Replace gh repo view with repository.Current() → 5 minutes
2. Enable API caching with ClientOptions → 30 minutes
3. Migrate repository features API calls to REST client → 1 hour

Total Time: ~1.5 hours
Impact: Immediate performance improvement and code simplification

Priority 2: Medium-Impact, Medium-Effort

1. Create unified pkg/github package with REST/GraphQL clients → 2-3 hours
2. Migrate file download logic to use REST client → 1 hour
3. Replace manual base64 decoding with native client features → 20 minutes

Total Time: ~4 hours
Impact: Better architecture, maintainability, and consistency

Priority 3: Long-Term Architecture

1. Full migration from shell-outs to native clients → 4-6 hours
2. Implement comprehensive error typing → 1 hour
3. Add pkg/auth integration for token management → 30 minutes

Total Time: ~6 hours
Impact: Modern, idiomatic Go code aligned with go-gh best practices

Performance Considerations

Shell-Out vs Native Client Benchmarks (Estimated)

Operation	Shell-Out	Native Client	Improvement
Get Repository	~50-100ms	~10-20ms	5-10x faster
GraphQL Query	~60-120ms	~15-30ms	4-8x faster
File Download	~100-200ms	~20-40ms	5-10x faster

Note: Actual performance depends on network latency, but native clients eliminate process spawning overhead.

Next Steps

1. Benchmark Current Performance: Establish baseline metrics for shell-out operations
2. Create GitHub Client Package: Start with pkg/github/client.go and repository.go
3. Implement Feature Flag: Allow toggling between shell-out and native clients
4. Migrate Incrementally: Start with repository features, then file operations
5. Add Integration Tests: Ensure both approaches work correctly
6. Update Documentation: Document new patterns and migration strategy

Conclusion

The upgrade to v2.13.0 is excellent and includes important fixes. However, the project is missing out on significant performance and maintainability benefits by exclusively using shell-out commands instead of the native REST and GraphQL clients provided by go-gh.

Key Insight: The current implementation treats go-gh as merely a wrapper around the gh CLI, when it actually provides powerful native API client capabilities that could eliminate process spawning overhead and simplify the codebase significantly.

Recommended Action: Start with the Priority 1 quick wins (1.5 hours total investment) to see immediate benefits, then plan the architectural improvements for long-term maintainability.

---

References:

• go-gh Documentation
• v2.13.0 Release Notes
• Security Advisory GHSA-g9f5-x53j-h563

Module summary saved to: specs/mods/cli-go-gh.md

AI generated by Go Fan

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by Go Fan.
🗺️ A newer treasure map awaits ye at Discussion #5928.
Fair winds, matey! 🏴‍☠️