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
- func DiscoverCompositeActionFiles(root string) ([]string, error)
- func DiscoverWorkflows() ([]string, error)
- func DiscoverWorkflowsIn(dir string) ([]string, error)
- func FindRepoRoot(startPath string) (string, error)
- func IsSelfRepositoryAction(value string) bool
- func KeyFromPath(workflowPath string) string
- func LocalActionRemoteUses(workflowPath, localPath string) []string
- func LookupRewrite(usesValue string, replacements map[string]string) (string, bool)
- func SelfRepositoryRefHasVersion(value string) bool
- func ValidateInRepo(path string) error
- func ValidatePathWithinRoot(root, candidate string) error
- type File
- func (f *File) ContainerImages() []uses.Image
- func (f *File) ExtractActionRefs() RefScan
- func (f *File) MigrateLocalActionsToSelfRepository() ([]byte, int, error)
- func (f *File) RewriteActionRefs(replacements map[string]string) ([]byte, int, error)
- func (f *File) UsesValues() []string
- func (f *File) ValidateRequiredActionRefRewrites(replacements map[string]string) (map[string]int, error)
- type LocalUse
- type RefScan
- type SelfRepositoryActionScan
- type SyntaxError
Constants ¶
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
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 ¶
DiscoverWorkflows finds all workflow files in .github/workflows/ relative to the current directory. Returns nil if the directory doesn't exist.
func DiscoverWorkflowsIn ¶
DiscoverWorkflowsIn finds all workflow files (*.yml, *.yaml) in dir. Returns nil if the directory doesn't exist.
func FindRepoRoot ¶ added in v0.1.6
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
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 ¶
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
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
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
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
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
ValidatePathWithinRoot resolves symlinks in candidate and rejects paths that leave root. Callers use it before reading or rewriting repository-owned YAML.
Types ¶
type File ¶
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 (*File) ContainerImages ¶ added in v0.3.0
ContainerImages returns the unpinned images the workflow's jobs run directly: `docker://` steps, the job container and service containers.
func (*File) ExtractActionRefs ¶
ExtractActionRefs finds and classifies all uses: references in the workflow.
func (*File) MigrateLocalActionsToSelfRepository ¶ added in v0.1.6
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 ¶
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
UsesValues returns every scalar `uses:` value in the file, as written.
type LocalUse ¶ added in v0.3.0
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