Documentation
¶
Overview ¶
Package pinreconcile implements the pin-reconciliation engine: adopting an external action-pin change back into the manifest and regenerating so every owned file agrees with it again.
Index ¶
- Variables
- func NewCommand() *cobra.Command
- func Run(opts Options) (bool, error)
- func RunOwnRepo(opts OwnRepoOptions) (bool, error)
- func SetActionPinSurgical(doc []byte, action, ref string) ([]byte, error)
- func StagePathspec(manifestPath string, pushWorkflows bool) []string
- func WriteCheckArtifact(path string, res CheckResult) error
- type Adoptions
- type CheckResult
- type Input
- type Options
- type OwnRepoOptions
Constants ¶
This section is empty.
Variables ¶
var ErrAmbiguousSource = errors.New("governed source files disagree on the action ref")
ErrAmbiguousSource means governed source files disagree on the ref for one action key. The engine refuses that key and falls through to a comment rather than guessing, matching the consensus-over-source rule.
Functions ¶
func NewCommand ¶
NewCommand creates the "reconcile" command: adopting an external governed action-pin change (for example a Dependabot bump landing in a generated workflow) back into the manifest's action_pins, then regenerating so every workflow the manifest produces agrees with it again. reconcile never pushes, commits, or merges; that stays a caller's job (a CI companion or a human).
func Run ¶
Run adopts a governed pin bump observed in opts.ChangedFiles into the user manifest's action_pins (verbatim, via SetActionPinSurgical) and regenerates every workflow the manifest produces so it agrees again. It reports whether anything actually changed; a converged tree is a safe no-op, which is the loop-termination guarantee a reconcile companion relies on.
func RunOwnRepo ¶
func RunOwnRepo(opts OwnRepoOptions) (bool, error)
RunOwnRepo adopts a governed pin bump observed in opts.ChangedFiles into cascade's own on-disk action_pins.yaml (a full re-marshal, since cascade owns that file outright, unlike the surgical user-manifest edit Run performs) and regenerates every workflow cascade's own manifest produces so it agrees again. It reports whether anything actually changed.
func SetActionPinSurgical ¶
SetActionPinSurgical changes a single action's value under ci.config.action_pins in a user manifest's raw bytes, touching nothing else. It walks the document as a yaml.Node tree rather than round-tripping through a typed struct, so every unrelated key, comment, and the document's key order survive byte for byte. A missing action_pins mapping (or a missing key inside it) is created rather than treated as an error, so a manifest that has never carried an override still adopts cleanly.
func StagePathspec ¶
StagePathspec returns the ONLY pathspec a reconcile commit may stage, so a crafted working-tree change cannot ride along (never git add -A). The common case is manifest-only (Contents: write); pushWorkflows is set only when a regenerate must push workflow files (the Workflows: write path).
func WriteCheckArtifact ¶
func WriteCheckArtifact(path string, res CheckResult) error
WriteCheckArtifact serializes the detector result for the companion to read.
Types ¶
type Adoptions ¶
Adoptions is the verbatim set to write into the manifest's action_pins map, keyed by action path. A sha adoption carries its trailing "# <version>".
func PlanAdoptions ¶
PlanAdoptions decides relevance and computes the verbatim adoptions. It reads the incoming ref from source with consensus-over-source, refuses on ambiguity, and never touches an ungoverned action. It performs no I/O.
type CheckResult ¶
type CheckResult struct {
Relevant bool `json:"relevant"`
ChangedRefs map[string]string `json:"changed_refs"`
}
CheckResult is the data-only detector output. The companions read it strictly as data (never executed) to decide whether to run and, if so, which governed refs changed. It never carries the target PR number: the companion derives that only from trusted workflow_run metadata.
func Check ¶
func Check(in Input) (CheckResult, error)
Check computes relevance without writing anything, so a fork-safe read-only job can run it. It reuses PlanAdoptions, so relevance and the changed set are exactly what a subsequent reconcile would adopt.
type Input ¶
Input is the source-agnostic reconcile input: the governed action set and, per governed action, every ref observed in an authoritative SOURCE file (the triggering change and, in cascade's own repo, hand-written workflows plus the anchor). Generated files are targets and are deliberately absent here.
type Options ¶
Options configures a user-repo Run. ManifestPath defaults to "<Root>/.github/manifest.yaml" when empty. ManifestKey defaults to config.DefaultManifestKey. ChangedFiles lists the paths (relative to Root, or absolute) of the source workflow files that triggered this reconcile; each is scanned line by line for governed "uses:" refs. These are the only files ever read as a ref SOURCE: every file the manifest itself produces is exclusively a regenerate TARGET and is never read back, so generation stays a pure offline function of the manifest.
type OwnRepoOptions ¶
type OwnRepoOptions struct {
Root string
ManifestPath string
ManifestKey string
ActionPinsPath string
ChangedFiles []string
}
OwnRepoOptions configures a RunOwnRepo. ManifestPath defaults to "<Root>/.github/manifest.yaml". ActionPinsPath names the on-disk action_pins.yaml cascade's own repo owns; it has no default because its location (internal/generate/action_pins.yaml in cascade's own tree) is not a convention any other repo shares. ChangedFiles lists the paths (relative to Root, or absolute) of the source files that triggered this reconcile: hand- written workflows and composite action definitions alike, since both carry governed pins.
Source Files