action

package
v1.0.0-beta.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2026 License: ISC Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const LockfileName = "preflight.lock"

LockfileName is the project lockfile that pins remote action refs to exact commit SHAs.

Variables

This section is empty.

Functions

func ActionUses 

func ActionUses(a *Action) []string

ActionUses returns all distinct uses refs referenced directly by the action's tasks, preserving first-seen order.

func IsRemoteCacheMiss 

func IsRemoteCacheMiss(err error) bool

IsRemoteCacheMiss reports whether err is a remote cache miss.

func IsRemoteRef 

func IsRemoteRef(ref string) bool

IsRemoteRef reports whether ref matches the supported remote action contract.

func PlaybookUses 

func PlaybookUses(pb *Playbook) []string

PlaybookUses returns all distinct uses refs referenced directly by the playbook's tasks, preserving first-seen order.

func ValidateActionYAML 

func ValidateActionYAML(data []byte) error

ValidateActionYAML validates an action document against the embedded JSON schema.

func ValidatePlaybookYAML 

func ValidatePlaybookYAML(data []byte) error

ValidatePlaybookYAML validates a playbook document against the embedded JSON schema.

func WriteFileAtomically 

func WriteFileAtomically(path string, data []byte, perm uint32) error

WriteFileAtomically writes data to path atomically using a temporary file and rename.

Types

type Action 

type Action struct {
	Name        string           `yaml:"name"`
	Version     string           `yaml:"version"`
	Description string           `yaml:"description"`
	Author      string           `yaml:"author"`
	Defaults    TaskDefaults     `yaml:"defaults" json:"defaults"`
	Inputs      map[string]Input `yaml:"inputs"`
	Tasks       []Task           `yaml:"tasks"`
}

Action is the parsed representation of an action.yml file.

func ParseAction 

func ParseAction(data []byte) (*Action, error)

ParseAction parses action YAML bytes into an Action.

func (*Action) Normalize 

func (a *Action) Normalize() error

Normalize canonicalizes all tasks in the action.

type CacheResolver 

type CacheResolver struct {
	CacheDir string
}

CacheResolver resolves versioned action refs from the local user cache at ~/.preflight/actions/. Refs of the form "github.com/org/name@v1.2" map to <cacheDir>/github.com/org/name@v1.2/action.yml.

func NewCacheResolver 

func NewCacheResolver(cacheDir string) *CacheResolver

NewCacheResolver creates a CacheResolver. If cacheDir is empty it defaults to ~/.preflight/actions/.

func (*CacheResolver) Name 

func (r *CacheResolver) Name() string

func (*CacheResolver) Resolve 

func (r *CacheResolver) Resolve(_ context.Context, ref string) (*Action, error)

type Chain 

type Chain []Resolver

Chain tries each Resolver in order, returning the first non-nil result. If no resolver handles the ref, it returns an error.

func DefaultChain 

func DefaultChain(projectDir string) Chain

DefaultChain builds the standard resolver chain: 

embedded stdlib → local ./actions/ → user cache → git (stub)

func (Chain) Fetch 

func (c Chain) Fetch(ctx context.Context, ref string) (*FetchResult, error)

Fetch tries each fetch-capable resolver in order, returning the first non-nil fetch result.

func (Chain) Resolve 

func (c Chain) Resolve(ctx context.Context, ref string) (*Action, error)

Resolve walks the chain and returns the first non-nil Action result.

type EmbeddedResolver 

type EmbeddedResolver struct {
	FS fs.FS
}

EmbeddedResolver resolves stdlib actions from an embedded filesystem. It handles refs with the "preflight/" prefix, mapping them to actions/preflight/<name>/action.yml inside the FS.

func NewEmbeddedResolver 

func NewEmbeddedResolver(fsys fs.FS) *EmbeddedResolver

NewEmbeddedResolver creates a resolver backed by the provided embedded FS.

func (*EmbeddedResolver) Name 

func (r *EmbeddedResolver) Name() string

Name returns a human-readable identifier for this resolver.

func (*EmbeddedResolver) Resolve 

func (r *EmbeddedResolver) Resolve(ctx context.Context, ref string) (*Action, error)

Resolve returns the Action for refs prefixed with "preflight/". Returns (nil, nil) for refs it does not handle.

type FetchResult 

type FetchResult struct {
	Entry  LockEntry
	Action *Action
}

FetchResult reports the pinned lock entry and parsed action for a fetched remote ref.

type Fetcher 

type Fetcher interface {
	Fetch(ctx context.Context, ref string) (*FetchResult, error)
}

Fetcher is implemented by resolvers that can acquire remote actions into the local cache.

type GitResolver 

type GitResolver struct {
	CacheDir     string
	LockfilePath string
	// contains filtered or unexported fields
}

GitResolver fetches action definitions from remote Git repositories. The ref format is "host/org/repo[/path/to/action]@version" or "host/org/repo[/path/to/action]@sha".

func NewGitResolver 

func NewGitResolver(cacheDir, lockfilePath string) *GitResolver

NewGitResolver creates a GitResolver that caches fetched actions in cacheDir and consults the project lockfile at lockfilePath.

func (*GitResolver) Fetch 

func (r *GitResolver) Fetch(ctx context.Context, ref string) (*FetchResult, error)

Fetch downloads the remote action into the pinned cache and updates the project lockfile.

func (*GitResolver) Name 

func (r *GitResolver) Name() string

func (*GitResolver) Resolve 

func (r *GitResolver) Resolve(_ context.Context, ref string) (*Action, error)

type Input 

type Input struct {
	Type        string `yaml:"type"` // string, bool, int, path
	Required    bool   `yaml:"required"`
	Default     any    `yaml:"default"`
	Description string `yaml:"description"`
}

Input describes a typed input parameter for an action.

type LocalResolver 

type LocalResolver struct {
	BaseDir string
}

LocalResolver resolves action refs from a local project actions directory. A ref like "myorg/display-config" maps to <BaseDir>/myorg/display-config/action.yml.

Refs that look like remote URLs (contain "://", start with "github.com/", etc.) are not handled by this resolver.

func NewLocalResolver 

func NewLocalResolver(baseDir string) *LocalResolver

NewLocalResolver creates a resolver that looks up actions under baseDir.

func (*LocalResolver) Name 

func (r *LocalResolver) Name() string

Name returns a human-readable identifier for this resolver.

func (*LocalResolver) Resolve 

func (r *LocalResolver) Resolve(ctx context.Context, ref string) (*Action, error)

Resolve returns the Action for a simple ref like "myorg/display-config". Returns (nil, nil) for refs that look like remote refs (contain a dot-separated hostname component, e.g. "github.com/…") or stdlib refs ("preflight/…").

type LockEntry 

type LockEntry struct {
	Ref    string `json:"ref"`
	SHA    string `json:"sha"`
	Pinned string `json:"pinned"` // original ref before SHA pinning
}

LockEntry records a pinned action reference.

func FetchRefs 

func FetchRefs(ctx context.Context, chain Chain, refs []string) ([]LockEntry, error)

FetchRefs fetches the full remote dependency closure reachable from refs. It traverses the complete action graph, resolving local and embedded refs to discover any remote deps they reference, so that nested remote actions under local or stdlib roots are fetched correctly.

type Lockfile 

type Lockfile struct {
	Actions map[string]LockEntry `json:"actions"`
}

Lockfile manages the preflight.lock file which pins remote action refs to exact Git SHAs for reproducible builds.

func LoadLockfile 

func LoadLockfile(path string) (*Lockfile, error)

LoadLockfile reads and parses a lockfile from path. If the file does not exist, an empty Lockfile is returned without error.

func (*Lockfile) Lookup 

func (l *Lockfile) Lookup(ref string) (LockEntry, bool)

Lookup returns the LockEntry for ref, or false if not pinned.

func (*Lockfile) Pin 

func (l *Lockfile) Pin(ref, sha string) error

Pin records a pinned SHA for the given ref.

func (*Lockfile) Save 

func (l *Lockfile) Save(path string) error

Save writes the lockfile to path as indented JSON.

type Playbook 

type Playbook struct {
	Name        string         `yaml:"name"`
	Description string         `yaml:"description"`
	Defaults    TaskDefaults   `yaml:"defaults" json:"defaults"`
	Vars        map[string]any `yaml:"vars"`
	Import      []string       `yaml:"import"`
	Tasks       []Task         `yaml:"tasks"`
}

Playbook is the parsed representation of a playbook.yml file.

func LoadPlaybookFile 

func LoadPlaybookFile(path string) (*Playbook, error)

LoadPlaybookFile reads a playbook and recursively merges any imported playbooks depth-first. Imported vars are merged first, then overridden by the importing playbook's vars; imported tasks are prepended in listed order.

func ParsePlaybook 

func ParsePlaybook(data []byte) (*Playbook, error)

ParsePlaybook parses playbook YAML bytes into a Playbook.

func (*Playbook) Normalize 

func (p *Playbook) Normalize() error

Normalize canonicalizes all tasks in the playbook.

type RemoteCacheMissError 

type RemoteCacheMissError struct {
	Ref string
}

RemoteCacheMissError reports that a remote action is not available from the current cache and lockfile state.

func (*RemoteCacheMissError) Error 

func (e *RemoteCacheMissError) Error() string

type RemoteRef 

type RemoteRef struct {
	Original   string
	Repository string
	ActionPath string
	Revision   string
}

RemoteRef is a parsed remote action ref of the form host/org/repo[/path/to/action]@rev.

func ParseRemoteRef 

func ParseRemoteRef(ref string) (*RemoteRef, error)

ParseRemoteRef parses a remote action ref into repository, optional action path, and revision components.

func (*RemoteRef) CloneURLs 

func (r *RemoteRef) CloneURLs() []string

CloneURLs returns candidate HTTPS clone URLs for the remote repository.

func (*RemoteRef) IsPinned 

func (r *RemoteRef) IsPinned() bool

IsPinned reports whether the revision already looks like a Git commit SHA.

func (*RemoteRef) PinnedRef 

func (r *RemoteRef) PinnedRef(sha string) string

PinnedRef returns the canonical SHA-pinned form of the ref while preserving the in-repo action path.

func (*RemoteRef) SourceDir 

func (r *RemoteRef) SourceDir(checkoutDir string) string

SourceDir resolves the action directory inside a checked-out repository.

type Resolver 

type Resolver interface {
	// Resolve returns the Action for the given ref, or (nil, nil) if this
	// resolver does not handle the ref.
	Resolve(ctx context.Context, ref string) (*Action, error)
	// Name returns a human-readable name for this resolver (for error messages).
	Name() string
}

Resolver resolves an action ref to an Action definition.

type Task 

type Task struct {
	Name         string         `yaml:"name"`
	ID           string         `yaml:"id"`
	Uses         string         `yaml:"uses"`
	With         map[string]any `yaml:"with"`
	Become       map[string]any `yaml:"become" json:"become,omitempty"`
	ModuleName   string         `yaml:"module"`
	ModuleParams map[string]any `yaml:"params"`
	Module       string         `yaml:"-"` // canonical module name
	Params       map[string]any `yaml:"-"` // canonical module params
	When         string         `yaml:"when"`
	DependsOn    []string       `yaml:"depends_on"`
	IgnoreErrors bool           `yaml:"ignore_errors"`
	Tags         []string       `yaml:"tags"`

	// InlineModules stores known inline module definitions by YAML module name.
	InlineModules map[string]map[string]any `yaml:"-"`
}

Task is a single step inside an action or playbook.

Module and Params are the canonical internal representation used after parsing/normalization. InlineModules preserves decode-time sugar for known inline module YAML keys.

func (*Task) Key 

func (t *Task) Key() string

func (*Task) ResolveModule 

func (t *Task) ResolveModule() error

ResolveModule canonicalizes a task into its internal module+params form. Returns an error if more than one inline module field is set, or if both "uses" and a concrete module are set.

func (*Task) UnmarshalYAML 

func (t *Task) UnmarshalYAML(value *yaml.Node) error

type TaskDefaults 

type TaskDefaults struct {
	Become map[string]any `yaml:"become" json:"become,omitempty"`
}

TaskDefaults describes execution defaults inherited by tasks.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.