gitlab

Documentation

Overview

Package gitlab resolves versions from a GitLab project's tags or releases, enriching candidates with the commit SHA the REST API returns for free.

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) 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) RecencyOrdered()
  • 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 GitLab 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 gitlab.com and the embedded clover app; a self-managed 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 injected PAT and explicit store (see credential), so a test never reaches the network and its auth path stays deterministic.

type Provider

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

Provider resolves versions from a GitLab project's tags or releases. The host is a per-marker value (gitlab.com or a self-managed 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 tags REST endpoint accepts order_by=version&sort=desc, so the listing is genuinely newest-first without the GraphQL detour GitHub needs.

func New

func New(opts ...Option) *Provider

New returns the GitLab 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 WithToken/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 from any source in the chain. It does not verify the token over the network - only that one is present - and never blocks on a prompt. Absence is reported as errAnonymous rather than a hard failure, since anonymous reads still work (just rate-limited).

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 GitLab accepts, in canonical order.

func (*Provider) Name

func (p *Provider) Name() string

Name identifies the provider.

func (*Provider) RecencyOrdered

func (p *Provider) RecencyOrdered()

RecencyOrdered marks the listing as newest-first, so a shallow lookup always holds the latest version; --deep is hinted only when a constrained marker finds no candidate while more pages remained.

func (*Provider) Resource

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

Resource validates a directive into a GitLab resource. The repository is the project's full path: at least namespace/project, with nested groups allowed (group/subgroup/project), unlike GitHub's strict owner/name.

func (*Provider) URL

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

URL builds the web page for a resolved candidate: the tag page for the candidate's ref. Every release has a tag, so the tag page serves both source=tags and source=releases. Empty when the ref is unknown.