source

Documentation

Overview

Package source fetches immutable, public GitHub Action source archives.

Index

• Constants
• func DigestTree(root string) (string, error)
• type Materialized
  • func (m Materialized) Release()
  • func (m Materialized) Retain(ctx context.Context) (Materialized, error)
• type NotPublicError
  • func (*NotPublicError) Error() string
• type Option
  • func WithActionResolutionSnapshot(root string, refresh bool) Option
  • func WithCacheMaxBytes(maxBytes int64) Option
  • func WithGitHubAPITokenProvider(provider func(context.Context) (string, error)) Option
  • func WithGitHubActionSourceTokenProvider(repository string, provider func(context.Context) (string, error)) Option
  • func WithLimits(compressed, expanded, perFile int64, entries int) Option
  • func WithTestEndpoints(apiBase string, codeloadBase ...string) Option
  • func WithUserAgentVersion(version string) Option
• type RateLimitError
  • func (e *RateLimitError) Error() string
• type Reference
  • func Parse(raw string) (Reference, error)
• type Resolved
• type Resolver
  • func NewResolver(client *http.Client, opts ...Option) (*Resolver, error)
  • func (r *Resolver) ResolutionSnapshotID() string
  • func (r *Resolver) Resolve(ctx context.Context, ref Reference) (Resolved, error)
• type Store
  • func NewStore(root string, client *http.Client, opts ...Option) (*Store, error)
  • func NewStoreContext(ctx context.Context, root string, client *http.Client, opts ...Option) (*Store, error)
  • func (s *Store) Materialize(ctx context.Context, resolved Resolved) (Materialized, error)

Constants

const (

	// UnsupportedContainerActionReason explains the supported alternative to docker:// actions.
	UnsupportedContainerActionReason = "docker:// container actions are unsupported; use a Dockerfile action or replace the action with a run step"
)

Functions

func DigestTree

func DigestTree(root string) (string, error)

DigestTree returns the canonical source digest for a local action directory. It uses the same bounded manifest and file-mode model as immutable remote action source. It rejects symlinks and other special files.

Types

type Materialized

type Materialized struct {
	RepositoryRoot string
	ActionRoot     string
	SourceDigest   string
	// contains filtered or unexported fields
}

Materialized identifies the immutable repository tree and selected action.

func (Materialized) Release

func (m Materialized) Release()

Release marks the materialized tree as no longer in use. Callers must release persistent-cache entries after reading them.

func (Materialized) Retain

func (m Materialized) Retain(ctx context.Context) (Materialized, error)

Retain acquires another lease for a memoized materialization.

type NotPublicError

type NotPublicError struct{}

NotPublicError deliberately does not distinguish missing and private repositories.

func (*NotPublicError) Error

func (*NotPublicError) Error() string

type Option

type Option func(*config) error

Option configures trusted process-level limits or test endpoints. Options must never be populated from workflow input.

func WithActionResolutionSnapshot

func WithActionResolutionSnapshot(root string, refresh bool) Option

WithActionResolutionSnapshot pins mutable refs to durable per-generation entries. Refresh starts a new generation without disrupting active readers.

func WithCacheMaxBytes

func WithCacheMaxBytes(maxBytes int64) Option

WithCacheMaxBytes bounds the immutable action-source cache. A materialized entry remains protected from eviction until its lease is released.

func WithGitHubAPITokenProvider

func WithGitHubAPITokenProvider(provider func(context.Context) (string, error)) Option

WithGitHubAPITokenProvider authenticates public action resolution without a repository-scoped token exception. It is intended for explicit local tools.

func WithGitHubActionSourceTokenProvider

func WithGitHubActionSourceTokenProvider(repository string, provider func(context.Context) (string, error)) Option

WithGitHubActionSourceTokenProvider authenticates mutable-ref API requests using a credential provisioned at the first such request and cached for this client. Returning an empty token selects anonymous resolution. Full lowercase SHAs never invoke the provider.

func WithLimits

func WithLimits(compressed, expanded, perFile int64, entries int) Option

WithLimits lowers or raises trusted archive limits.

func WithTestEndpoints

func WithTestEndpoints(apiBase string, codeloadBase ...string) Option

WithTestEndpoints replaces the API base and, when supplied, the direct codeload base. It exists for hermetic tests; production callers should use defaults.

func WithUserAgentVersion

func WithUserAgentVersion(version string) Option

WithUserAgentVersion identifies the buildkite-gha client making requests.

type RateLimitError

type RateLimitError struct{ Reset time.Time }

RateLimitError reports anonymous GitHub API exhaustion.

func (*RateLimitError) Error

func (e *RateLimitError) Error() string

type Reference

type Reference struct{ Owner, Repository, Path, Ref, Raw string }

Reference is a parsed remote action reference.

func Parse

func Parse(raw string) (Reference, error)

Parse parses owner/repository[/path]@ref.

type Resolved

type Resolved struct {
	Reference    Reference
	Commit       string
	SourceDigest string
}

Resolved pins a requested reference to an immutable commit.

type Resolver

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

Resolver resolves public GitHub references, optionally using a credential only for GitHub API requests. Requests discard the client's cookie jar.

func NewResolver

func NewResolver(client *http.Client, opts ...Option) (*Resolver, error)

func (*Resolver) ResolutionSnapshotID

func (r *Resolver) ResolutionSnapshotID() string

ResolutionSnapshotID identifies the immutable mutable-ref generation.

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, ref Reference) (Resolved, error)

Resolve pins a ref to a commit. Full lowercase SHA pins bypass mutable refs.

type Store

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

Store downloads exact public commits directly from codeload and atomically caches them in an existing real directory. A Store must not be shared by mutually untrusted processes writing the same cache root.

func NewStore

func NewStore(root string, client *http.Client, opts ...Option) (*Store, error)

func NewStoreContext

func NewStoreContext(ctx context.Context, root string, client *http.Client, opts ...Option) (*Store, error)

func (*Store) Materialize

func (s *Store) Materialize(ctx context.Context, resolved Resolved) (Materialized, error)

Materialize returns the verified repository and selected action identity.