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 EnsureSentinel(content []byte) []byte
- func ExtractLocalCompositeRefs(workflowPath string, localPaths []string) ([]parserlock.ActionRef, []string)
- func FindRepoRoot(startPath string) string
- func IsSelfRepositoryAction(value string) bool
- func KeyFromPath(workflowPath string) string
- func SelfRepositoryRefHasVersion(value string) bool
- func ValidatePathWithinRoot(root, candidate string) error
- type File
- type RefScan
- type SelfRepositoryActionScan
Constants ¶
const SentinelComment = "# This workflow is managed by gh actions-lock."
SentinelComment is prepended to workflow files managed by gh actions-lock so users can tell at a glance that the file's action refs are locked.
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 EnsureSentinel ¶ added in v0.1.0
EnsureSentinel prepends the sentinel comment to the workflow content if it is not already present at the top of the file. The comment is placed before any existing content with a blank line separating it from the YAML body.
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 git repository root containing startPath, or "" when startPath is not inside a git repository.
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.
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
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.
Source Files