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 ExtractLocalCompositeRefs(workflowPath string, localPaths []string) ([]parserlock.ActionRef, []string)
- func FindRepoRoot(startPath string) (string, error)
- func IsSelfRepositoryAction(value string) bool
- func KeyFromPath(workflowPath string) string
- func SelfRepositoryRefHasVersion(value string) bool
- func ValidatePathWithinRoot(root, candidate string) error
- type File
- 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) ValidateRequiredActionRefRewrites(replacements map[string]string) (map[string]int, error)
- type RefScan
- type SelfRepositoryActionScan
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 ExtractLocalCompositeRefs ¶
func ExtractLocalCompositeRefs(workflowPath string, localPaths []string) ([]parserlock.ActionRef, []string)
ExtractLocalCompositeRefs reads action.yml files from local paths relative to the workflow file's directory and returns any repository action refs found in their steps.
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 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 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) 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.
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
// Warnings are non-fatal parse notes (e.g. expression-based uses:).
Warnings []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
LocalPaths []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
Warnings []string
}
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.