githubauth

Documentation

Overview

Package githubauth resolves the github-update-go agent's effective GitHub credential at startup. It mirrors the github-releaser agent's resolution order: GitHub App installation token, or startup error. Extracted into its own package so the resolution outcomes are unit-testable against an httptest IAT endpoint (the pattern lib/githubapp tests already use).

Index

• Variables
• func Resolve(ctx context.Context, cfg Config) (string, error)
• type AuthMode
  • func ResolveAuthMode(appID, installationID int64, pemKeyFile, pemKey string) AuthMode
• type Config
• type Configurator
  • func NewGhAuthSetupGit(ghToken string) Configurator
  • func NewNoopAuthSetup() Configurator

Variables

var ErrAppCredentialsRequired = stderrors.New(
	"github-update-go auth: App credentials required",
)

ErrAppCredentialsRequired is returned (wrapped) when no usable GitHub App credentials are configured at startup. Exposed as a sentinel so callers and tests can match it via errors.Is rather than string comparison.

Functions

func Resolve

func Resolve(ctx context.Context, cfg Config) (string, error)

Resolve returns the single effective GitHub token for the agent.

• App mode: mints an installation access token via lib/githubapp.MintIAT (preferring PEMKeyFile over PEMKey when both are set).
• None: returns a non-nil error naming the required App env vars.

The returned token is the bearer credential wired to the GitOps clone/push URLs, the gh CLI seam, and the Claude subprocess env. It is never logged in full (MintIAT logs only token_prefix).

Token lifetime (known constraint): the App-mode IAT is minted ONCE at startup and is valid for ~1 hour (GitHub's max IAT lifetime); it is not refreshed during the run. A github-update-go task — clone, update, gate, push, draft PR — completes well under the IAT lifetime for typical repos.

Types

type AuthMode

type AuthMode int

AuthMode classifies which credential type is active at pod startup.

const (
	// AuthModeNone means no usable App credential is configured; the caller
	// falls back to a raw GH_TOKEN (local cmd/run-task) or refuses to start.
	AuthModeNone AuthMode = iota
	// AuthModeGitHubApp means App credentials are present and an IAT will
	// be minted.
	AuthModeGitHubApp
)

func ResolveAuthMode

func ResolveAuthMode(appID, installationID int64, pemKeyFile, pemKey string) AuthMode

ResolveAuthMode picks the credential type to use at startup.

• AppID>0 AND InstallationID>0 AND (PEMKeyFile set OR PEMKey set) → AuthModeGitHubApp
• else → AuthModeNone

type Config

type Config struct {
	AppID          int64
	InstallationID int64
	PEMKeyFile     string
	PEMKey         string
	BaseURL        string
}

Config carries the raw credential inputs read from env/flags. Either a PEM file path (PEMKeyFile) or PEM env content (PEMKey) may be supplied; PEMKeyFile is preferred when both are present. BaseURL overrides the GitHub API base (defaults to https://api.github.com); tests point it at an httptest server.

type Configurator

type Configurator interface {
	Setup(ctx context.Context) error
}

Configurator configures git credential helpers for GitHub at pod startup. The pod implementation invokes `gh auth setup-git`; the local-CLI noop returns nil without touching any config file.

func NewGhAuthSetupGit

func NewGhAuthSetupGit(ghToken string) Configurator

NewGhAuthSetupGit returns a Configurator that invokes `gh auth setup-git` when ghToken is non-empty. When ghToken is empty the Setup call is a no-op.

The token is bound into the exec wrapper here so the gh subprocess receives GH_TOKEN in its env — without that, gh inherits the pod env (which has no token under GitHub App auth) and dies with "You are not logged into any GitHub hosts" even though the IAT was minted successfully.

func NewNoopAuthSetup

func NewNoopAuthSetup() Configurator

NewNoopAuthSetup returns a Configurator that always returns nil. Used by cmd/run-task so the developer's existing gh auth login continues to handle credentials; ~/.gitconfig is never mutated by the agent.