lockfile

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package lockfile is the source of truth for the workflow dependency lockfile format and pin grammar.

Parsing as a security boundary

ParseActionRef is the choke point. Untrusted uses: strings enter; only concrete repository actions leave. Everything else — expressions, docker:// images, local paths, reusable workflows, control characters — returns nil, before it can reach a URL or GraphQL builder.

ParseReusableWorkflowRef is its mirror: the reusable-workflow shape ParseActionRef rejects, parsed through the same validation. Both split the ref at the first @, never the last — a ref may legitimately contain one.

owner/repo/path pass isValidSegment: a fixed character set, ".."/"." barred. Drop-in safe. The ref is looser by necessity — git refs carry slashes, dots, even another @ — so isValidRef only guarantees it cannot escape a quoted literal or smuggle a traversal. A ref still needs escaping before it touches a URL path. Owner/repo do not.

Hand-rolled, no regexp, allocation-free, single-pass: it runs per dependency on the hot path and the reject-lists must stay auditable at a glance. They are load-bearing. Do not refactor them into regular expressions.

Index

Constants

View Source 
const Path = ".github/workflows/actions.lock"

Path is the canonical repo-relative location of the dependency lockfile.

View Source 
const Version = "v0.0.1"

Version is the only supported lockfile schema version.

Variables

View Source 
var ErrFutureVersion = errors.New("lockfile version is newer than this binary supports")

ErrFutureVersion is the sentinel returned (via errors.Is) when Parse refuses a lockfile whose schema version is newer than this binary supports. External consumers (e.g. Dependabot) can detect this specific failure mode without scraping the error string.

Functions

func IndexKey 

func IndexKey(owner, repo, ref string) string

IndexKey builds the normalized lookup key for a dependency entry without the digest: "OWNER/REPO@REF".

func IsFullSha 

func IsFullSha(s string) bool

IsFullSha reports whether s looks like a full commit hash (SHA-1 or SHA-256). Callers use this to distinguish bare-SHA `uses:` refs from symbolic refs.

func IsLocalReusableWorkflow 

func IsLocalReusableWorkflow(localPath string) bool

IsLocalReusableWorkflow reports whether a `./...`-prefixed local `uses:` value names a reusable workflow file (rather than a local composite action directory). Exposed for consumers that walk workflows themselves and need to distinguish the two shapes.

func Schema 

func Schema() string

Schema returns the embedded JSON Schema document for the supported lockfile version. Callers can surface it for editor integration or external validation. Parse checks the document's shape — known keys, required fields, version — and canonicalizes pin keys, but does not reject entries whose keys aren't canonical pins; they're preserved for consumer diagnostics. Note the schema's pin pattern constrains pin *values* (the workflow and uses arrays), not the dependencies map keys, so schema validation alone won't enforce that every dependency key is a canonical pin either.

func ShortSHA 

func ShortSHA(s string) string

ShortSHA returns the first 12 characters of a SHA, or the full string if shorter. Used for human-readable log and diagnostic output.

func SplitNWO 

func SplitNWO(nwo string) (owner, repo string, ok bool)

SplitNWO splits an owner/repo (Name-With-Owner) string into its two components. It returns ok=false for inputs that don't carry both an owner and a repo segment: the empty string, anything without a slash, a leading slash ("/repo"), and a trailing slash without a repo ("owner/").

For inputs with extra path segments ("owner/repo/sub/..."), only the first two segments are returned; the remainder is dropped. This matches Dependency.OwnerRepo and the lockfile's repo-granularity pin grammar (sub-action paths are graph traversal details, not pin identity).

SplitNWO does not validate the owner/repo character set — use ParseActionRef when parsing a verbatim `uses:` value where stricter charset rules apply.

Types

type Action 

type Action struct {
	Tag     string   `yaml:"tag,omitempty"`
	Branch  string   `yaml:"branch,omitempty"`
	Commit  string   `yaml:"commit,omitempty"`
	OwnerID int64    `yaml:"owner_id"`
	RepoID  int64    `yaml:"repo_id"`
	Uses    []string `yaml:"uses,omitempty"`
}

Action carries the per-action metadata recorded in the lockfile under the pin key.

Tag is the discovered release/tag at the commit, if one exists. Optional.

Branch is a branch that contains the pinned commit. Required: a commit not on any branch is an impostor / fork-network signal, so Parse rejects an Action without one. It is the authenticity check that SHA-only pinning lacks.

Commit holds the digest in algo-prefixed form (e.g. "sha1-..." or "sha256-..."). Required.

Uses lists the action's direct nested dependencies (composite action `uses:` steps) as canonical pin keys. Empty for leaf actions; required for composites, a condition Parse can't enforce structurally.

type ActionMeta 

type ActionMeta struct {
	Name       string
	Execution  ExecutionType
	NestedUses []string
}

ActionMeta is the parsed subset of `action.yml` (or `action.yaml`) relevant to dependency resolution: the action's name, how it executes, and composite action nested `uses:` strings.

func ParseActionMeta 

func ParseActionMeta(content string) (*ActionMeta, error)

ParseActionMeta parses the contents of an action.yml file into an ActionMeta. Composite actions emit their nested step `uses:` strings in NestedUses; non-composite actions return an empty NestedUses.

Returns an error only on malformed YAML — unknown `runs.using` values resolve to ExecUnknown rather than failing.

type ActionRef 

type ActionRef struct {
	Owner string // e.g. "actions"
	Repo  string // e.g. "checkout"
	Path  string // e.g. "save" for actions/cache/save@v4
	Ref   string // tag, branch, or full SHA as written after `@`
	Raw   string // original `uses:` string (post-trim)
}

ActionRef is a parsed `uses:` reference to a repository action. It captures only the components the lockfile grammar cares about: owner, repo, optional sub-action path, ref string, and the original raw value for diagnostics.

ParseActionRef is the only constructor; consumers should treat zero values as invalid.

func ParseActionRef 

func ParseActionRef(uses string) *ActionRef

ParseActionRef parses a `uses:` string into an ActionRef. It returns nil for any input that is not a repository action — expression-based refs, local paths, docker images, reusable workflow files, or any input whose owner/repo/path/ref components are unsafe to hand to the downstream URL/GraphQL builders (control characters, traversal tokens, or quote/whitespace metacharacters in the ref).

The returned pointer is non-nil iff the input names a real repository action (composite or javascript) at owner/repo[/path]@ref.

func (ActionRef) FullName 

func (a ActionRef) FullName() string

FullName returns owner/repo or owner/repo/path. Used for human-facing display and for graph traversal where distinct sub-paths must be treated as distinct nodes.

func (ActionRef) NWO 

func (a ActionRef) NWO() string

NWO returns owner/repo (Name With Owner). Zero-value ActionRefs return the empty string.

type ExecutionType 

type ExecutionType string

ExecutionType describes how an action runs. 

const (
	ExecNode      ExecutionType = "node"
	ExecDocker    ExecutionType = "docker"
	ExecComposite ExecutionType = "composite"
	ExecUnknown   ExecutionType = "unknown"
)

type File 

type File struct {
	Version      string              `yaml:"version"`
	Dependencies map[string]Action   `yaml:"dependencies"`
	Workflows    map[string][]string `yaml:"workflows"`
	// contains filtered or unexported fields
}

File is the parsed lockfile shape. 

# .github/workflows/actions.lock
version: v0.0.1
workflows:
  .github/workflows/deploy.yml:
    - actions/checkout@v6:sha1-8e8c483db84b4bee98b60c0593521ed34d9990e8
dependencies:
  actions/checkout@v4.3.1:sha1-34e114876b0b11c390a56381ad16ebd13914f8d5:
    tag: v4.3.1
    branch: main
    commit: sha1-34e114876b0b11c390a56381ad16ebd13914f8d5
    owner_id: 44036562
    repo_id: 197814629
    uses:
      - actions/cache@v4.0.0:sha1-...

The Go field `Dependencies` maps to the YAML key `dependencies:` — the lockfile's deduplicated action DAG. Each entry's `uses:` list names the action's direct nested dependencies, reusing the same canonical pin keys. Workflow entries hold the full transitive closure as a flat list of pin keys for cold readability.

func Parse 

func Parse(contents []byte) (File, error)

Parse unmarshals YAML lockfile contents and verifies the version is supported. It enforces structural validity — unknown top-level keys are rejected and required fields must be present — but does not validate pin integrity (e.g. whether a SHA actually matches the ref) or action existence. That belongs to the consumer (e.g. gh-actions-pin's check command).

Action map keys and workflow dependency entries are canonicalized via ParsePin so downstream lookups by canonical key (e.g. pin.String()) match regardless of the source casing of owner/repo/algo/hex in the YAML. Entries that do not parse as a valid pin are left untouched; consumers can flag them via diagnostics. Workflow path keys are NOT canonicalized — filesystem paths are case-sensitive on the platforms we run on.

func (File) KeyPosition 

func (f File) KeyPosition(path ...string) (line, col int, ok bool)

KeyPosition is like Position but resolves the position of the final path segment's *key* node rather than its value. It is the right anchor for map entries whose key is the meaningful token (e.g. a dependency pin key or a workflow path under "workflows").

func (File) LookupWorkflow 

func (f File) LookupWorkflow(workflowKey string) ([]string, bool)

LookupWorkflow returns the dependency closure for the given repo-relative workflow key (e.g. ".github/workflows/deploy.yml"). The returned bool reports whether the key was found.

func (File) Position 

func (f File) Position(path ...string) (line, col int, ok bool)

Position returns the 1-indexed line and column of the value node reached by following path as a sequence of mapping keys from the lockfile root (e.g. Position("version") points at the version value). ok is false when the path can't be resolved or no node tree was retained.

type ParseError 

type ParseError struct {
	Line   int
	Column int
	Msg    string
	// contains filtered or unexported fields
}

ParseError describes a failure to parse a dependency lockfile.

Line and Column, when non-zero, are the 1-indexed position within the lockfile contents that the failure refers to. They index the lockfile itself, never a consumer's workflow file, so callers can anchor diagnostics on the lockfile (.github/workflows/actions.lock) rather than scraping yaml.v3's error string themselves.

Column is populated for semantic failures Parse detects itself (it walks the retained YAML node tree to the offending key/value). It is left zero for raw yaml.v3 decode failures, whose errors report only a line: a malformed document has no node tree to read a column from, and yaml.v3 type errors carry a line but no column.

Msg is the human-readable reason with yaml.v3's "yaml:" package prefix and leading position removed.

func (*ParseError) Error 

func (e *ParseError) Error() string

func (*ParseError) Unwrap 

func (e *ParseError) Unwrap() error

type Pin 

type Pin struct {
	NWO   string // "actions/checkout"
	Owner string // "actions"
	Repo  string // "checkout"
	Ref   string // "v4"
	Algo  string // "sha1"
	Hex   string // "34e114876b0b11c390a56381ad16ebd13914f8d5"
}

Pin holds the parsed components of a dependency pin key. 

"OWNER/REPO@REF:ALGO-HEX"

The pin identifies a downloaded action tarball at repo+SHA granularity — matching the runner, which downloads `owner/repo@sha` once per ref and reuses the tree for any sub-action path. Sub-action paths (e.g. the `save` in `actions/cache/save@v4`) are graph traversal details, not pin identity, and do not appear in this serialized form.

func ParsePin 

func ParsePin(s string) (Pin, bool)

ParsePin parses a pin string of the canonical form: 

"OWNER/REPO@REF:ALGO-HEX"

Returns ok=false if the string doesn't match the expected format, including any sub-action path component (e.g. "owner/repo/sub@ref:...") — the lockfile grammar is strictly repo-scoped, matching the runner's tarball download identity.

func (Pin) Canonical 

func (p Pin) Canonical() Pin

Canonical returns a copy of p with all case-insensitive components (owner, repo, algo, hex) normalized to lowercase. Ref preserves source casing — git refs are case-sensitive.

This is the single normalization point for the lockfile pin grammar: String, IndexKey, and ParsePin all funnel through it, so callers never need their own ToLower bookkeeping when handing pins through this package.

func (Pin) IndexKey 

func (p Pin) IndexKey() string

IndexKey returns the normalized lookup key for this pin without the digest: "OWNER/REPO@REF".

func (Pin) String 

func (p Pin) String() string

String returns the canonical pin form: "OWNER/REPO@REF:ALGO-HEX". This doubles as the actions-map key in the lockfile.

type ReusableWorkflowRef 

type ReusableWorkflowRef struct {
	Owner string // e.g. "octo"
	Repo  string // e.g. "workflows"
	Path  string // e.g. ".github/workflows/release.yml"
	Ref   string // tag, branch, or full SHA as written after `@`
	Raw   string // original `uses:` string (post-trim)
}

ReusableWorkflowRef is a parsed `uses:` reference to a reusable workflow file — the owner/repo/.github/workflows/<name>.yml@ref shape that ParseActionRef deliberately rejects. It carries the same components as ActionRef; Path is the in-repo workflow file path (e.g. ".github/workflows/release.yml"), and Ref is the full ref as written after the FIRST `@`, so a ref containing `@` survives intact.

ParseReusableWorkflowRef is the only constructor; treat zero values as invalid.

func ParseReusableWorkflowRef 

func ParseReusableWorkflowRef(uses string) *ReusableWorkflowRef

ParseReusableWorkflowRef parses the *remote* reusable-workflow `uses:` shape that ParseActionRef rejects: owner/repo/.github/workflows/<name>.yml@ref. It returns nil for anything that is not a remote reusable workflow — repository actions, expression refs, docker images, or any input whose components are unsafe for the downstream URL/GraphQL builders.

It deliberately rejects LOCAL reusable workflows (./.github/workflows/...); those have no owner/repo and a different resolution path. Use IsLocalReusableWorkflow for that shape. It also rejects nested paths such as .github/workflows/sub/ci.yml: GitHub reusable workflows live directly under .github/workflows/, so only a single file segment is accepted.

It is the mirror of ParseActionRef for the reusable shape, and shares the same first-`@` split and security validation. Downstream consumers that must derive a reusable workflow's repository and file path (e.g. to locate that repo's detached lockfile) should use this rather than hand-rolling the split: a naive last-`@` split mis-parses refs that contain `@`.

The returned pointer is non-nil iff the input names a reusable workflow file at owner/repo/.github/workflows/<name>.{yml,yaml}@ref.

func (ReusableWorkflowRef) FullName 

func (r ReusableWorkflowRef) FullName() string

FullName returns owner/repo/path — the fully-qualified reusable workflow identity.

func (ReusableWorkflowRef) NWO 

func (r ReusableWorkflowRef) NWO() string

NWO returns owner/repo (Name With Owner). Zero-value refs return the empty string.

type SemVer 

type SemVer struct {
	Prefix string // "v" or ""
	Major  int
	Minor  int
	Patch  int
	Rest   string // anything after patch (e.g. "-beta.1")
	Raw    string
}

SemVer holds parsed semantic version components.

API stability: the type and its comparison helpers (Greater, Narrows, UpgradeOver, MajorTag, MinorTag, IsFull) are part of the exported surface because the tag recommendation engine in downstream consumers relies on them. Their semantics are deliberately non-strict-semver (see below) and are committed to as-is; they are not internal helpers despite the recommendation-engine flavor.

GitHub Actions has no first-class version scheme — a uses: ref can be any git ref (tag, branch, SHA, or even "main"). In practice most action authors follow semver-ish conventions, but the ecosystem diverges from strict semver in ways that golang.org/x/mod/semver cannot handle: bare versions without a "v" prefix ("2.0.0"), partial versions ("v4", "v4.2"), and arbitrary suffixes all appear in the wild. x/mod/semver rejects bare and partial tags, and doesn't expose individual components — we need Major/Minor/Patch to compute MajorTag, MinorTag, and IsFull for the tag recommendation engine.

func ParseSemVer 

func ParseSemVer(tag string) (SemVer, bool)

ParseSemVer parses a version tag into its components. Returns false if the tag doesn't look like a version (or is a full SHA that happens to start with a digit).

func (SemVer) Greater 

func (s SemVer) Greater(o SemVer) bool

Greater reports whether s should be preferred over o: higher major.minor.patch wins; on a tie a stable version beats a pre-release, a v-prefixed tag beats the same bare version, then a lexicographic compare of the raw tags provides a deterministic final tie-break.

func (SemVer) IsFull 

func (s SemVer) IsFull() bool

IsFull returns true if the version has all three components (major.minor.patch) and no pre-release suffix. Tags like "v4" or "v4.2" return false.

func (SemVer) IsMajorOnly 

func (s SemVer) IsMajorOnly() bool

IsMajorOnly reports whether the raw tag is a bare major version (e.g. "v4").

func (SemVer) IsMutable 

func (s SemVer) IsMutable() bool

IsMutable reports whether this version is a partial (major-only or major.minor) tag that should be narrowed to a specific patch version.

func (SemVer) IsStable 

func (s SemVer) IsStable() bool

IsStable returns true if the tag has no pre-release suffix or trailing junk.

func (SemVer) MajorTag 

func (s SemVer) MajorTag() string

MajorTag returns the major-only tag string (e.g. "v4").

func (SemVer) MinorTag 

func (s SemVer) MinorTag() string

MinorTag returns the major.minor tag string (e.g. "v4.2").

func (SemVer) Narrows 

func (s SemVer) Narrows(other SemVer) bool

Narrows reports whether s is a more specific patch version of other. e.g. other="v4", s="v4.1.0" → true; other="v4.2", s="v4.2.1" → true.

func (SemVer) UpgradeOver 

func (s SemVer) UpgradeOver(other SemVer) bool

UpgradeOver reports whether s represents a real version upgrade over other. Returns false for noops where other is already at or more specific than s.

Source Files

View all Source files

Directories

Path Synopsis
internal
cmd/genschema command

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.