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(forge.Code)) error
• 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) Color(dark bool) color.Color
  • func (p *Provider) Commit(ctx context.Context, r provider.Resource, tag string) (string, error)
  • func (p *Provider) Credentialed(r provider.Resource) bool
  • func (p *Provider) Dated()
  • 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) DownloadAsset(ctx context.Context, r provider.Resource, asset model.Asset) (io.ReadCloser, error)
  • func (p *Provider) Identify(r provider.Resource) (string, string)
  • 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(forge.Code)) error

Login runs the GitHub device flow against host and stores the minted token under it; see forge.DeviceLogin.

Types

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.

func (*Provider) Color

func (p *Provider) Color(dark bool) color.Color

Color is the provider's brand color. See provider.Provider.Color.

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, so --verify can check a pin even for a tag off the discovered page. The lookup is namespace-explicit - git/ref/tags/, peeling an annotated tag via git/tags/ - because the commits/{ref} endpoint resolves any ref-like string and prefers a branch over a same-named tag, which would let a crafted tag borrow a benign branch's commit and pass verification.

func (*Provider) Credentialed

func (p *Provider) Credentialed(r provider.Resource) bool

Credentialed reports whether a credential applies to the resource's host, satisfying provider.CredentialChecker. It gates the default verification tier, so an anonymous rate limit is never spent on verification the user did not ask for.

func (*Provider) Dated

func (p *Provider) Dated()

Dated marks the listing as date-bearing: releases carry a publication date. Bare tags do not, and fall to the post-discovery date check.

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) DownloadAsset

func (p *Provider) DownloadAsset(
	ctx context.Context,
	r provider.Resource,
	asset model.Asset,
) (io.ReadCloser, error)

DownloadAsset streams a release asset's content, satisfying provider.AssetDownloader. With a credential the asset is read through its API endpoint (Accept: application/octet-stream), which authorizes a private repository's download where the browser URL 404s; anonymously the browser URL is fetched directly. The bearer is attached only when the API URL shares the host's API origin, so a forged asset URL cannot redirect the token, and any redirect off that origin (the CDN, a subdomain, a scheme downgrade) drops the header.

func (*Provider) Identify

func (p *Provider) Identify(r provider.Resource) (string, string)

Identify returns the owner/name repository and its landing page.

func (*Provider) Keys

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

Keys reports the directive keys GitHub accepts, in canonical order. Exactly one of repository and tool is required, which Resource enforces.

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.

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.