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

pin

package
v0.0.13 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package pin implements the two-phase pin lifecycle: Plan builds a complete Record of what to pin (pure computation + network reads), and Commit writes the Record to disk (workflow files + lockfile).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Commit 

func Commit(ctx context.Context, rec *Record, store *lockfile.State, copts *CommitOptions) error

Commit writes a planned Record to disk: rewrites workflow files and updates the lockfile store. All-or-nothing semantics — if any write fails, previously written files are not rolled back (best-effort), but the error is returned immediately.

Types

type CommitOptions 

type CommitOptions struct {
	// OnProgress is called at each phase boundary. Nil means no progress.
	OnProgress func(phase string)
}

CommitOptions configures the Commit pass.

type Entry 

type Entry struct {
	NWO          string     `json:"nwo"`
	Ref          string     `json:"ref"`
	SHA          string     `json:"sha,omitempty"`
	ObservedSHA  string     `json:"observed_sha,omitempty"`
	Resolution   Resolution `json:"resolution"`
	Issue        string     `json:"issue,omitempty"`
	Reason       string     `json:"reason,omitempty"`
	Suggestion   string     `json:"suggestion,omitempty"`
	AutoFixedRef string     `json:"auto_fixed_ref,omitempty"` // original ref before sane-release rewrite
	OnBranch     string     `json:"on_branch,omitempty"`
	Tag          string     `json:"tag,omitempty"`
	Workflows    []string   `json:"workflows"`
	RequiredBy   []string   `json:"required_by,omitempty"`
	Direct       bool       `json:"direct"`
	FullScan     bool       `json:"full_scan,omitempty"`
}

Entry records the plan decision for one action dependency.

type PlanOptions 

type PlanOptions struct {
	Resolver  *resolve.Resolver
	Tagger    *tag.Lister
	Store     *lockfile.State
	Pool      *pinpool.Pool
	RepoOwner string // for same-owner narrowing skip
	RepoName  string
	Version   string // CLI version for the record
	// NoNarrow disables tag narrowing: mutable version refs (v4, v3.1)
	// are kept as the lock comment instead of being resolved to full
	// patch tags (v4.2.1). Bare-SHA reverse lookup still applies.
	NoNarrow bool

	// OnProgress is called at each phase boundary with a human-readable
	// label (e.g. "Resolving actions/checkout"). Nil means no progress.
	OnProgress func(phase string)
	// contains filtered or unexported fields
}

PlanOptions configures the Plan pass.

type Record 

type Record struct {
	Entries   []Entry
	Workflows []WorkflowPlan // internal, omitted from JSON
	Repo      *RepoInfo
	Version   string
	Created   time.Time
}

Record is the complete output of Plan — everything Commit needs to write all changes atomically, and the authoritative run-log artifact.

func Plan 

func Plan(ctx context.Context, report *checks.Report, opts PlanOptions) (*Record, error)

Plan walks an actionmanager Report and produces a Record describing every pin action to take. It does network reads (resolve, reverse lookup, reachability) but no disk writes.

func (*Record) Investigated 

func (r *Record) Investigated() []Entry

Investigated returns entries with Resolution == Investigate.

func (*Record) MarshalJSON 

func (r *Record) MarshalJSON() ([]byte, error)

MarshalJSON produces the run-log JSON with schema, tool info, summary, and deduplicated action entries.

func (*Record) Pinned 

func (r *Record) Pinned() []Entry

Pinned returns entries with Resolution == Pinned.

func (*Record) Unresolved 

func (r *Record) Unresolved() []Entry

Unresolved returns entries with Resolution == Unresolved.

func (*Record) Valid 

func (r *Record) Valid() bool

Valid reports whether the record contains no investigate or unresolved entries.

func (*Record) WriteJSON 

func (r *Record) WriteJSON() (string, error)

WriteJSON writes the record as indented JSON to the cache directory, garbage-collecting old logs. Returns the file path.

type RepoInfo 

type RepoInfo struct {
	Owner string `json:"owner,omitempty"`
	Name  string `json:"name,omitempty"`
	Host  string `json:"host,omitempty"`
}

RepoInfo identifies the repository the run scanned.

type Resolution 

type Resolution string

Resolution describes the outcome for a single action reference. 

const (
	Pinned      Resolution = "pinned"
	Verified    Resolution = "verified"
	Investigate Resolution = "needs-investigation"
	Skipped     Resolution = "skipped"
	Unresolved  Resolution = "unresolved"
)

Resolution values reported for an action reference.

func (Resolution) MarshalJSON 

func (r Resolution) MarshalJSON() ([]byte, error)

MarshalJSON emits the resolution string.

func (Resolution) String 

func (r Resolution) String() string

String returns the resolution as a string.

func (*Resolution) UnmarshalJSON 

func (r *Resolution) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a resolution string.

type Summary 

type Summary struct {
	Workflows     int  `json:"workflows"`
	Actions       int  `json:"actions"`
	Valid         bool `json:"valid"`
	Pinned        int  `json:"pinned"`
	AlreadyPinned int  `json:"already_pinned"`
	FullScan      int  `json:"full_scan"`
	Investigate   int  `json:"needs_investigation"`
	Skipped       int  `json:"skipped"`
	Unresolved    int  `json:"unresolved"`
}

Summary is the run's roll-up: counts by resolution.

type WorkflowPlan 

type WorkflowPlan struct {
	Path     string
	Rewrites map[string]string
}

WorkflowPlan records what Commit must write for one workflow file. Internal to the pin lifecycle; not serialized.

Source Files

View all Source files

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.