feat: add GitHub CLI authentication support

Add support for using GitHub CLI (`gh`) as an authentication provider for Hermit via a user config (`gh-cli-auth`), enabling seamless integration with `gh auth token`.
This simplifies authentication for private packages and repositories by eliminating the need to manually set HERMIT_GITHUB_TOKEN.

Author: Lachlan Donald

app/main.go

@@ -18,6 +18,7 @@ import (
 	"github.com/cashapp/hermit"
 	"github.com/cashapp/hermit/cache"
 	"github.com/cashapp/hermit/github"
+	"github.com/cashapp/hermit/github/auth"
 	"github.com/cashapp/hermit/state"
 	"github.com/cashapp/hermit/ui"
 	"github.com/cashapp/hermit/util/debug"
@@ -167,14 +168,6 @@ func Main(config Config) {
 		cli = &unactivated{cliBase: common}
 	}
 
-	githubToken := os.Getenv("HERMIT_GITHUB_TOKEN")
-	if githubToken == "" {
-		githubToken = os.Getenv("GITHUB_TOKEN")
-		p.Tracef("GitHub token set from GITHUB_TOKEN")
-	} else {
-		p.Tracef("GitHub token set from HERMIT_GITHUB_TOKEN")
-	}
-
 	kongOptions := []kong.Option{
 		kong.Groups{
 			"env":    "Environment:\nCommands for creating and managing environments.",
@@ -209,6 +202,23 @@ func Main(config Config) {
 		log.Fatalf("failed to initialise CLI: %s", err)
 	}
 
+	ctx, err := parser.Parse(os.Args[1:])
+	parser.FatalIfErrorf(err)
+	configureLogging(cli, ctx.Command(), p)
+
+	var userConfig UserConfig
+	userConfigPath := cli.getUserConfigFile()
+
+	if IsUserConfigExists(userConfigPath) {
+		p.Tracef("Loading user config from: %s", userConfigPath)
+		userConfig, err = LoadUserConfig(userConfigPath)
+		if err != nil {
+			log.Printf("%s: %s", userConfigPath, err)
+		}
+	} else {
+		p.Tracef("No user config found at: %s", userConfigPath)
+	}
+
 	var envInfo *hermit.EnvInfo
 	if isActivated {
 		envInfo, err = hermit.LoadEnvInfo(envPath)
@@ -217,13 +227,36 @@ func Main(config Config) {
 		}
 	}
 
+	// Initialize GitHub token
+	var githubToken string
+	if envInfo != nil && len(envInfo.Config.GitHubTokenAuth.Match) > 0 {
+		// Determine provider based on user config
+		providerType := "env"
+		if userConfig.GHCliAuth {
+			providerType = "gh-cli"
+		}
+
+		provider, err := auth.NewProvider(providerType, p)
+		if err != nil {
+			p.Tracef("Failed to create GitHub token provider: %v", err)
+		} else {
+			token, err := provider.GetToken()
+			if err != nil {
+				p.Tracef("Failed to get GitHub token from provider %s: %v", providerType, err)
+			} else {
+				githubToken = token
+				p.Tracef("GitHub token set from provider: %s", providerType)
+			}
+		}
+	}
+
 	getSource := config.PackageSourceSelector
 	if config.PackageSourceSelector == nil {
 		getSource = cache.GetSource
 	}
 	defaultHTTPClient := config.defaultHTTPClient(p)
 
-	ghClient := github.New(defaultHTTPClient, githubToken)
+	ghClient := github.New(p, defaultHTTPClient, githubToken)
 	if envInfo != nil {
 		// If the environment has been configured to use GitHub token
 		// authentication for any patterns, wrap the
@@ -245,23 +278,6 @@ func Main(config Config) {
 		log.Fatalf("failed to open cache: %s", err)
 	}
 
-	ctx, err := parser.Parse(os.Args[1:])
-	parser.FatalIfErrorf(err)
-	configureLogging(cli, ctx.Command(), p)
-
-	var userConfig UserConfig
-	userConfigPath := cli.getUserConfigFile()
-
-	if IsUserConfigExists(userConfigPath) {
-		p.Tracef("Loading user config from: %s", userConfigPath)
-		userConfig, err = LoadUserConfig(userConfigPath)
-		if err != nil {
-			log.Printf("%s: %s", userConfigPath, err)
-		}
-	} else {
-		p.Tracef("No user config found at: %s", userConfigPath)
-	}
-
 	config.State.LockTimeout = cli.getLockTimeout()
 	sta, err = state.Open(hermit.UserStateDir, config.State, cache)
 	if err != nil {

app/user_config.go

@@ -29,6 +29,7 @@ type UserConfig struct {
 	NoGit       bool          `hcl:"no-git,optional" help:"If true Hermit will never add/remove files from Git automatically."`
 	Idea        bool          `hcl:"idea,optional" help:"If true Hermit will try to add the IntelliJ IDEA plugin automatically."`
 	Defaults    hermit.Config `hcl:"defaults,block,optional" help:"Default configuration values for new Hermit environments."`
+	GHCliAuth   bool          `hcl:"gh-cli-auth,optional" help:"If true, use GitHub CLI (gh) for token authentication instead of environment variables."`
 }
 
 // IsUserConfigExists checks if the user config file exists at the given path.

docs/docs/usage/user-config-schema.hcl

@@ -8,6 +8,8 @@ short-prompt = boolean # (optional)
 no-git = boolean # (optional)
 # If true Hermit will try to add the IntelliJ IDEA plugin automatically.
 idea = boolean # (optional)
+# If true, use GitHub CLI (gh) for token authentication instead of environment variables.
+gh-cli-auth = boolean # (optional)
 # Default configuration values for new Hermit environments.
 defaults = {
   # Package manifest sources.

github/api.go

@@ -13,6 +13,7 @@ import (
 	"sync"
 
 	"github.com/cashapp/hermit/errors"
+	"github.com/cashapp/hermit/ui"
 )
 
 // Repo information.
@@ -44,14 +45,14 @@ type Client struct {
 }
 
 // New creates a new GitHub API client.
-func New(client *http.Client, token string) *Client {
+func New(ui *ui.UI, client *http.Client, token string) *Client {
 	if client == nil {
 		client = http.DefaultClient
 	}
 	if token == "" {
 		client = http.DefaultClient
 	} else {
-		client = &http.Client{Transport: TokenAuthenticatedTransport(client.Transport, token)}
+		client = &http.Client{Transport: TokenAuthenticatedTransport(ui, client.Transport, token)}
 	}
 	return &Client{client: client}
 }

github/auth/provider.go

@@ -0,0 +1,88 @@
+package auth
+
+import (
+	"os"
+	"os/exec"
+	"strings"
+	"sync"
+
+	"github.com/cashapp/hermit/errors"
+	"github.com/cashapp/hermit/ui"
+)
+
+// Provider is an interface for GitHub token providers
+type Provider interface {
+	// GetToken returns a GitHub token or an error if one cannot be obtained
+	GetToken() (string, error)
+}
+
+// EnvProvider implements Provider using environment variables
+type EnvProvider struct {
+	ui *ui.UI
+}
+
+// GetToken returns a token from environment variables
+func (p *EnvProvider) GetToken() (string, error) {
+	p.ui.Debugf("Getting GitHub token from environment variables")
+	if token := os.Getenv("HERMIT_GITHUB_TOKEN"); token != "" {
+		p.ui.Tracef("Using HERMIT_GITHUB_TOKEN for GitHub authentication")
+		return token, nil
+	}
+	if token := os.Getenv("GITHUB_TOKEN"); token != "" {
+		p.ui.Tracef("Using GITHUB_TOKEN for GitHub authentication")
+		return token, nil
+	}
+	p.ui.Tracef("No GitHub token found in environment")
+	return "", errors.New("no GitHub token found in environment")
+}
+
+// GHCliProvider implements Provider using the gh CLI tool
+type GHCliProvider struct {
+	// cache the token and only refresh when needed
+	token     string
+	tokenLock sync.Mutex
+	ui        *ui.UI
+}
+
+// GetToken returns a token from gh CLI
+func (p *GHCliProvider) GetToken() (string, error) {
+	p.ui.Debugf("Getting GitHub token from gh CLI")
+	p.tokenLock.Lock()
+	defer p.tokenLock.Unlock()
+
+	// Return cached token if available
+	if p.token != "" {
+		return p.token, nil
+	}
+
+	// Check if gh is installed
+	ghPath, err := exec.LookPath("gh")
+	if err != nil {
+		return "", errors.New("gh CLI not found in PATH")
+	}
+
+	p.ui.Tracef("gh CLI found in PATH: %s", ghPath)
+
+	// Run gh auth token
+	cmd := exec.Command("gh", "auth", "token")
+	output, err := cmd.Output()
+	if err != nil {
+		return "", errors.Wrap(err, "failed to get token from gh CLI")
+	}
+
+	p.ui.Tracef("gh auth token output: %s", string(output))
+	p.token = strings.TrimSpace(string(output))
+	return p.token, nil
+}
+
+// NewProvider creates a new token provider based on the specified type
+func NewProvider(providerType string, ui *ui.UI) (Provider, error) {
+	switch providerType {
+	case "env", "":
+		return &EnvProvider{ui: ui}, nil
+	case "gh-cli":
+		return &GHCliProvider{ui: ui}, nil
+	default:
+		return nil, errors.Errorf("unknown GitHub token provider: %s", providerType)
+	}
+}

github/auth/provider_test.go

@@ -0,0 +1,125 @@
+package auth
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"testing"
+
+	"github.com/alecthomas/assert/v2"
+	"github.com/cashapp/hermit/ui"
+)
+
+func TestEnvProvider(t *testing.T) {
+	ui, _ := ui.NewForTesting()
+	provider := &EnvProvider{ui: ui}
+
+	t.Run("no tokens set", func(t *testing.T) {
+		os.Unsetenv("HERMIT_GITHUB_TOKEN")
+		os.Unsetenv("GITHUB_TOKEN")
+		token, err := provider.GetToken()
+		assert.Error(t, err)
+		assert.Equal(t, "", token)
+	})
+
+	t.Run("HERMIT_GITHUB_TOKEN set", func(t *testing.T) {
+		t.Setenv("HERMIT_GITHUB_TOKEN", "hermit-token")
+		t.Setenv("GITHUB_TOKEN", "")
+		token, err := provider.GetToken()
+		assert.NoError(t, err)
+		assert.Equal(t, "hermit-token", token)
+	})
+
+	t.Run("GITHUB_TOKEN set", func(t *testing.T) {
+		t.Setenv("HERMIT_GITHUB_TOKEN", "")
+		t.Setenv("GITHUB_TOKEN", "github-token")
+		token, err := provider.GetToken()
+		assert.NoError(t, err)
+		assert.Equal(t, "github-token", token)
+	})
+
+	t.Run("both tokens set, HERMIT_GITHUB_TOKEN takes precedence", func(t *testing.T) {
+		t.Setenv("HERMIT_GITHUB_TOKEN", "hermit-token")
+		t.Setenv("GITHUB_TOKEN", "github-token")
+		token, err := provider.GetToken()
+		assert.NoError(t, err)
+		assert.Equal(t, "hermit-token", token)
+	})
+}
+
+func TestGHCliProvider(t *testing.T) {
+	ui, _ := ui.NewForTesting()
+	provider := &GHCliProvider{ui: ui}
+
+	t.Run("gh not installed", func(t *testing.T) {
+		t.Setenv("PATH", "")
+
+		token, err := provider.GetToken()
+		assert.Error(t, err)
+		assert.Equal(t, "", token)
+		assert.Contains(t, err.Error(), "gh CLI not found")
+	})
+
+	t.Run("token caching", func(t *testing.T) {
+		// Skip if gh not installed
+		if _, err := exec.LookPath("gh"); err != nil {
+			t.Skip("gh CLI not installed")
+		}
+
+		// First call should get a real token
+		token1, err := provider.GetToken()
+		if err != nil {
+			t.Skip("gh auth token failed, probably not authenticated")
+		}
+		assert.NotEqual(t, "", token1)
+
+		// Second call should return cached token
+		token2, err := provider.GetToken()
+		assert.NoError(t, err)
+		assert.Equal(t, token1, token2)
+	})
+}
+
+func TestNewProvider(t *testing.T) {
+	tests := []struct {
+		name        string
+		provider    string
+		wantType    Provider
+		wantErrText string
+	}{
+		{
+			name:     "env provider",
+			provider: "env",
+			wantType: &EnvProvider{},
+		},
+		{
+			name:     "empty string defaults to env",
+			provider: "",
+			wantType: &EnvProvider{},
+		},
+		{
+			name:     "gh-cli provider",
+			provider: "gh-cli",
+			wantType: &GHCliProvider{},
+		},
+		{
+			name:        "unknown provider",
+			provider:    "unknown",
+			wantErrText: "unknown GitHub token provider: unknown",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ui, _ := ui.NewForTesting()
+			got, err := NewProvider(tt.provider, ui)
+			if tt.wantErrText != "" {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), tt.wantErrText)
+				return
+			}
+			assert.NoError(t, err)
+			assert.Equal(t, fmt.Sprintf("%T", tt.wantType), fmt.Sprintf("%T", got))
+		})
+	}
+}

github/http.go

@@ -1,15 +1,19 @@
+//go:build !localgithub
+
 package github
 
 import (
 	"net/http"
+
+	"github.com/cashapp/hermit/ui"
 )
 
 // TokenAuthenticatedTransport returns a HTTP transport that will inject a
 // GitHub authentication token into any requests to github.com.
 //
 // Conceptually similar to
 // https://github.com/google/go-github/blob/d23570d44313ca73dbcaadec71fc43eca4d29f8b/github/github.go#L841-L875
-func TokenAuthenticatedTransport(transport http.RoundTripper, token string) http.RoundTripper {
+func TokenAuthenticatedTransport(_ *ui.UI, transport http.RoundTripper, token string) http.RoundTripper {
 	if transport == nil {
 		transport = http.DefaultTransport
 	}