github

Documentation

Overview

Package github resolves versions from GitHub releases/tags, enriches candidates with commit SHAs, and sources checksums via an ordered chain.

Index

• func Login(ctx context.Context, host, clientID string, prompt func(Code)) error
• type Code
• type Option
  • func WithStore(s tokenStore) Option
  • func WithToken(tok string) Option
  • func WithTransport(rt http.RoundTripper) Option
• type Provider
  • func New(opts ...Option) *Provider
  • func (p *Provider) AuthHint() string
  • func (p *Provider) Authenticate(context.Context) error
  • func (p *Provider) Branches(ctx context.Context, r provider.Resource) ([]provider.Branch, error)
  • func (p *Provider) Commit(ctx context.Context, r provider.Resource, tag string) (string, error)
  • func (p *Provider) DefaultBranch(ctx context.Context, r provider.Resource) (string, error)
  • func (p *Provider) Describe(r provider.Resource) string
  • func (p *Provider) Discover(ctx context.Context, r provider.Resource) ([]model.Candidate, error)
  • func (p *Provider) Keys() []provider.Key
  • func (p *Provider) Name() string
  • func (p *Provider) Reachable(ctx context.Context, r provider.Resource, branch, commit string) (bool, error)
  • func (p *Provider) Resource(d directive.Directive) (provider.Resource, error)
  • func (p *Provider) URL(r provider.Resource, c model.Candidate) string

Functions

func Login

func Login(ctx context.Context, host, clientID string, prompt func(Code)) error

Login runs the GitHub device flow against host and stores the minted token: it requests a code, hands it to prompt so the caller can show it to the user, polls until the user authorises in the browser, then persists the token under the host so the credential chain finds it. It needs no client secret and binds no local port, so it works headless. host and clientID default to github.com and the embedded clover app; a GitHub Enterprise Server host has no embeddable app, so it requires an explicit --client-id. The context bounds the poll.

Types

type Code

type Code struct {
	UserCode        string
	VerificationURL string
}

Code is the user-facing half of the device flow: the one-time code to enter and the URL to enter it at.

type Option

type Option func(*Provider)

Option configures a Provider.

func WithStore

func WithStore(s tokenStore) Option

WithStore sets the token store the credential chain reads the clover-minted token from, for tests.

func WithToken

func WithToken(tok string) Option

WithToken injects a host-bound PAT credential directly, for tests exercising the authenticated path (and the exfil guard) without reading the machine's environment.

func WithTransport

func WithTransport(rt http.RoundTripper) Option

WithTransport overrides the HTTP transport, for tests. It also pins credential resolution to the explicit store (see credential), so a test never reaches the network and its auth path - GraphQL vs anonymous REST - is fully deterministic.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider resolves versions from GitHub tags or releases. The host is a per-marker value (github.com or a GitHub Enterprise Server instance), so the REST client is host-agnostic - each request carries its own absolute URL and its own per-host token - while one shared, cached, rate-limited transport covers every marker in a run. The REST client serves the anonymous path (GraphQL rejects unauthenticated requests); a GraphQL client, built per host since go-gh maps the host to its /api/graphql endpoint, lists tags in a real newest-first order when a credential is present.

func New

func New(opts ...Option) *Provider

New returns the GitHub provider, wiring the token store the credential chain reads from. A store that cannot be located (no config dir) is left nil, so the chain simply skips that rung. The default keychain store is wired only on the real transport: a test transport keeps auth explicit (via WithStore), so the machine's stored token never leaks into a test's auth path.

func (*Provider) AuthHint

func (p *Provider) AuthHint() string

AuthHint returns how to authenticate when no credential is found.

func (*Provider) Authenticate

func (p *Provider) Authenticate(context.Context) error

Authenticate reports whether a credential is available for the default host, without verifying it over the network or blocking on a prompt. A login stored under a non-default host is keyed by host and only resolved at discovery, so this may under-report for those. Absence is reported as errAnonymous rather than a hard failure, since anonymous reads still work (just rate-limited).

func (*Provider) Branches

func (p *Provider) Branches(ctx context.Context, r provider.Resource) ([]provider.Branch, error)

Branches lists the repository's branches with their tip commits, for matching an allowed-branch pattern and the tip-equality fast path. It always paginates to exhaustion - a release branch (e.g. v1.12) can sort well past the first page - since a partial list could silently miss the allowed branch.

func (*Provider) Commit

func (p *Provider) Commit(ctx context.Context, r provider.Resource, tag string) (string, error)

Commit resolves a tag to its peeled commit SHA, satisfying provider.Committer. The /commits/{ref} endpoint resolves any ref - including an annotated tag - to the commit it points at, so --verify can check a pin even for a tag off the discovered page.

func (*Provider) DefaultBranch

func (p *Provider) DefaultBranch(ctx context.Context, r provider.Resource) (string, error)

DefaultBranch returns the repository's default branch, for tag-on-trunk verification when no explicit allowed-branch pattern is set.

func (*Provider) Describe

func (p *Provider) Describe(r provider.Resource) string

Describe returns a human-readable label for a resource.

func (*Provider) Discover

func (p *Provider) Discover(ctx context.Context, r provider.Resource) ([]model.Candidate, error)

Discover lists candidate versions for a resource from tags or releases.

func (*Provider) Keys

func (p *Provider) Keys() []provider.Key

Keys reports the directive keys GitHub accepts, in canonical order.

func (*Provider) Name

func (p *Provider) Name() string

Name identifies the provider.

func (*Provider) Reachable

func (p *Provider) Reachable(
	ctx context.Context,
	r provider.Resource,
	branch, commit string,
) (bool, error)

Reachable reports whether commit is an ancestor of (or equal to) branch's tip, via the compare API: a base that is "behind" or "identical" to the head contains it.

func (*Provider) Resource

func (p *Provider) Resource(d directive.Directive) (provider.Resource, error)

Resource validates a directive into a GitHub resource.

func (*Provider) URL

func (p *Provider) URL(r provider.Resource, c model.Candidate) string

URL builds the web page for a resolved candidate: the release/tag page for the candidate's ref. The releases/tag form renders for a plain tag too, so it serves both source=tags and source=releases. Empty when the ref is unknown.