Help us shape the future of Go! Take the 2026 Go Developer Survey

workflowfile

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package workflowfile owns the parsed workflow YAML representation: loading, extraction of action refs, local composite discovery, and comment-preserving rewriting. It intentionally has no dependency on the lockfile or resolver packages.

Index

Constants

View Source
const RepoRootEnv = "GH_ACTIONS_LOCK_REPO_ROOT"

RepoRootEnv overrides `.git` discovery for callers relocking a partial checkout without `.git`. The workflow's directory must lie inside it.

Variables

This section is empty.

Functions

func DiscoverCompositeActionFiles added in v0.1.6

func DiscoverCompositeActionFiles(root string) ([]string, error)

DiscoverCompositeActionFiles walks the repository rooted at root and returns the paths of all action definition files (action.yml / action.yaml). The .git directory is skipped. Non-composite action files are included; callers migrate them with MigrateLocalActionsToSelfRepository, which no-ops when a file has no local `./…` steps.

func DiscoverWorkflows

func DiscoverWorkflows() ([]string, error)

DiscoverWorkflows finds all workflow files in .github/workflows/ relative to the current directory. Returns nil if the directory doesn't exist.

func DiscoverWorkflowsIn

func DiscoverWorkflowsIn(dir string) ([]string, error)

DiscoverWorkflowsIn finds all workflow files (*.yml, *.yaml) in dir. Returns nil if the directory doesn't exist.

func FindRepoRoot added in v0.1.6

func FindRepoRoot(startPath string) (string, error)

FindRepoRoot returns the repository root containing startPath, or "" when startPath is not inside a git repository. RepoRootEnv overrides discovery; an unusable override is an error.

func IsSelfRepositoryAction added in v0.1.6

func IsSelfRepositoryAction(value string) bool

IsSelfRepositoryAction reports whether a `uses:` value is a self repository action reference (`$/…`). These resolve against the defining repo at the running commit and need no lockfile SHA.

func KeyFromPath

func KeyFromPath(workflowPath string) string

KeyFromPath converts a workflow path discovered on disk (relative to the repo root or cwd) into the repo-relative key used inside the lockfile.

func LocalActionRemoteUses added in v0.3.0

func LocalActionRemoteUses(workflowPath, localPath string) []string

LocalActionRemoteUses returns the remote actions that the composite at the `./…` path localPath uses, read from the checkout containing workflowPath. It returns nil when the action can't be read there: the runner workspace may hold something else, so nothing is known about it.

func LookupRewrite added in v0.3.0

func LookupRewrite(usesValue string, replacements map[string]string) (string, bool)

LookupRewrite returns the replacement for a `uses:` value: an exact key, else, for a sub-path action owner/repo/path@ref, a key owner/repo@ref.

func SelfRepositoryRefHasVersion added in v0.1.6

func SelfRepositoryRefHasVersion(value string) bool

SelfRepositoryRefHasVersion reports whether a `$/…` value carries an `@ref` suffix. A self repository reference always resolves to the running ref, so any `@ref` is invalid — the malformed form `$/actions/foo@v1`.

func ValidateInRepo added in v0.3.0

func ValidateInRepo(path string) error

ValidateInRepo rejects a path that resolves, through symlinks, outside the repository containing it. A path outside any repository, or one that does not exist yet, has nothing to escape.

func ValidatePathWithinRoot added in v0.1.6

func ValidatePathWithinRoot(root, candidate string) error

ValidatePathWithinRoot resolves symlinks in candidate and rejects paths that leave root. Callers use it before reading or rewriting repository-owned YAML.

Types

type File

type File struct {
	Path    string
	Content []byte
	// contains filtered or unexported fields
}

File is the parsed workflow YAML the CLI rewrites in-place. It carries the original byte content alongside the parsed node tree so RewriteActionRefs can do anchored, comment-preserving substitution.

func Load

func Load(path string) (*File, error)

Load reads and parses a workflow file.

func Parse

func Parse(path string, content []byte) (*File, error)

Parse builds a File from already-loaded workflow content.

func (*File) ContainerImages added in v0.3.0

func (f *File) ContainerImages() []uses.Image

ContainerImages returns the unpinned images the workflow's jobs run directly: `docker://` steps, the job container and service containers.

func (*File) ExtractActionRefs

func (f *File) ExtractActionRefs() RefScan

ExtractActionRefs finds and classifies all uses: references in the workflow.

func (*File) MigrateLocalActionsToSelfRepository added in v0.1.6

func (f *File) MigrateLocalActionsToSelfRepository() ([]byte, int, error)

MigrateLocalActionsToSelfRepository rewrites same-repo `./…` composite action references to the inherently-pinned `$/…` form. Only local paths that resolve to an in-repo action file are rewritten — that in-repo existence is the same-repo equivalence guard that makes `$/` a safe replacement for `./`. Local reusable workflows are never candidates (ExtractActionRefs excludes them). Returns the new content and the number of `uses:` lines changed.

func (*File) RewriteActionRefs

func (f *File) RewriteActionRefs(replacements map[string]string) ([]byte, int, error)

RewriteActionRefs rewrites targeted uses: refs in the original workflow content while preserving the surrounding formatting and comments.

func (*File) UsesValues added in v0.3.0

func (f *File) UsesValues() []string

UsesValues returns every scalar `uses:` value in the file, as written.

func (*File) ValidateRequiredActionRefRewrites added in v0.2.0

func (f *File) ValidateRequiredActionRefRewrites(replacements map[string]string) (map[string]int, error)

ValidateRequiredActionRefRewrites rejects replacements that cannot be applied without changing every alias of an anchored scalar.

type LocalUse added in v0.3.0

type LocalUse struct {
	Path   string
	Parent string
}

LocalUse is a `./…` use and the `$/…` action whose steps contain it.

type RefScan added in v0.1.6

type RefScan struct {
	// Refs are remote repository action references (owner/repo[/path]@ref).
	Refs []parserlock.ActionRef
	// LocalPaths are `./…` local composite action references (reusable
	// workflows are excluded — they resolve differently).
	LocalPaths []string
	// SelfRepositoryRefs are valid `$/…` self repository actions. Inherently
	// pinned: they resolve against the defining repo at the running ref.
	SelfRepositoryRefs []string
	// SelfRepositoryActionRefs are the step-level subset that must be scanned
	// locally for remote dependencies. Job-level refs point at reusable
	// workflows, which the workflow discovery pass scans independently.
	SelfRepositoryActionRefs []string
	// SelfRepositoryRefErrs are malformed `$/…@ref` values — the invalid form.
	SelfRepositoryRefErrs []string
	// MalformedRefs are the errors for `uses:` values the Actions backend
	// rejects (uses.Invalid). They are never skipped.
	MalformedRefs []string
}

RefScan is the classified result of walking a workflow's `uses:` values.

type SelfRepositoryActionScan added in v0.1.6

type SelfRepositoryActionScan struct {
	Refs                  []parserlock.ActionRef
	SelfRepositoryRefs    []string
	SelfRepositoryRefErrs []string
	// LocalUses are the `./…` uses inside the scanned actions, each with the
	// `$/…` action that contains it.
	LocalUses     []LocalUse
	MalformedRefs []string
	// ActionFiles are the in-repo action definition files visited, in visit
	// order. Refs in these files are rewritable source, unlike `$/…` itself.
	ActionFiles []string
	Errors      []string
	// Images are the mutable `docker://` steps in the visited actions.
	Images []uses.Image
}

SelfRepositoryActionScan is the transitive dependency scan of in-repo actions reached from step-level `$/…` references.

func ScanSelfRepositoryActions added in v0.1.6

func ScanSelfRepositoryActions(workflowPath string, actionRefs []string) SelfRepositoryActionScan

ScanSelfRepositoryActions recursively reads in-repo actions reached through step-level `$/…` references. The self repository actions themselves remain inherently pinned; only remote dependencies found inside them are returned in Refs.

type SyntaxError added in v0.3.0

type SyntaxError struct {
	Err error
}

SyntaxError reports content that isn't valid YAML, as opposed to a file that couldn't be read or a document that parsed but was rejected.

func (*SyntaxError) Error added in v0.3.0

func (e *SyntaxError) Error() string

func (*SyntaxError) Unwrap added in v0.3.0

func (e *SyntaxError) Unwrap() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL