ci

Documentation

Index

• func FormatHandoffMessage(r *HandoffResult) string
• func HandoffDepth() int
• func IsBranchHeadFresh(ciCtx *CIContext) bool
• func RunSubsystem(reg Registry, subsystem string, ctx context.Context, cfg *config.Config, ...) error
• func ValidSubsystems() []string
• type CIContext
  • func ResolveContext() *CIContext
  • func (c *CIContext) IsBranch() bool
  • func (c *CIContext) IsCI() bool
  • func (c *CIContext) IsTag() bool
• type HandoffDecision
• type HandoffResult
  • func EvaluateHandoff(ciCtx *CIContext, handoff config.DependencyHandoff, commitSHA string) *HandoffResult
• type Registry
• type RunOptions
• type Runner

Functions

func FormatHandoffMessage

func FormatHandoffMessage(r *HandoffResult) string

FormatHandoffMessage returns a human-readable message for the handoff result. Returns empty string when no message is needed.

func HandoffDepth

func HandoffDepth() int

HandoffDepth reads SF_CI_HANDOFF_DEPTH from the environment. Returns 0 when unset or unparseable (original pipeline, not a handoff).

func IsBranchHeadFresh

func IsBranchHeadFresh(ciCtx *CIContext) bool

IsBranchHeadFresh returns true if the CI SHA still matches the remote branch HEAD. Shipping actions (release, docs sync, catalog publish) must call this before performing externally visible mutations. Returns true when not in CI or when the branch cannot be resolved (fail-open for local runs).

func RunSubsystem

func RunSubsystem(reg Registry, subsystem string, ctx context.Context, cfg *config.Config, ciCtx *CIContext, opts RunOptions) error

RunSubsystem dispatches to a subsystem runner by name. Returns a clear error for unknown subsystem names.

func ValidSubsystems

func ValidSubsystems() []string

ValidSubsystems returns the list of valid subsystem names.

Types

type CIContext

type CIContext struct {
	Provider      string // gitlab, github, gitea, forgejo, jenkins
	Event         string // push, tag, merge_request, schedule
	Branch        string // current branch (empty on tags)
	Tag           string // current tag (empty on branches)
	SHA           string // full commit SHA
	DefaultBranch string // repo default branch name
	RepoURL       string // repository URL
	Workspace     string // working directory
	PipelineID    string // provider pipeline/run ID (for cancel API)
}

CIContext holds normalized CI environment information. Provider skeletons translate forge-native vars into SF_CI_* env vars; CIContext reads those to provide a provider-neutral execution context.

func ResolveContext

func ResolveContext() *CIContext

ResolveContext reads SF_CI_* env vars to build a CIContext. Falls back to git inspection for local (non-CI) runs.

func (*CIContext) IsBranch

func (c *CIContext) IsBranch() bool

IsBranch returns true when the current context is a branch build (not a tag).

func (*CIContext) IsCI

func (c *CIContext) IsCI() bool

IsCI returns true when running in a CI environment (SF_CI_PROVIDER is set).

func (*CIContext) IsTag

func (c *CIContext) IsTag() bool

IsTag returns true when the current context is a tag build.

type HandoffDecision

type HandoffDecision int

HandoffDecision describes the outcome of a handoff evaluation.

const (
	// HandoffNone — no handoff needed (continue mode, or no commit created).
	HandoffNone HandoffDecision = iota
	// HandoffRestart — new commit pushed, requesting pipeline restart on repaired revision.
	HandoffRestart
	// HandoffSuppressed — handoff would fire, but this pipeline already originated
	// from a repaired-revision handoff (depth >= 1). One-hop guard prevents infinite loops.
	HandoffSuppressed
	// HandoffFail — repair was needed but policy says fail if handoff can't proceed.
	HandoffFail
)

type HandoffResult

type HandoffResult struct {
	Decision  HandoffDecision
	CommitSHA string // SHA of the new commit deps created
	Triggered bool   // true if a new pipeline was triggered via provider API
	Stale     bool   // true if current pipeline SHA != branch HEAD (should stop shipping)
	Depth     int    // current handoff depth from SF_CI_HANDOFF_DEPTH
}

HandoffResult describes what happened when deps attempted a pipeline handoff.

func EvaluateHandoff

func EvaluateHandoff(ciCtx *CIContext, handoff config.DependencyHandoff, commitSHA string) *HandoffResult

EvaluateHandoff checks whether a dependency commit requires pipeline handoff.

Handoff fires only when ALL of these are true:

1. A new commit SHA was created and pushed
2. Handoff mode is restart_pipeline
3. Handoff depth is 0 (original pipeline, not already a rerun)

When depth >= 1 and a new commit was still created, the decision is HandoffSuppressed — the one-hop guard prevents infinite restart loops.

When handoff is "continue", the decision is always HandoffNone. When handoff is "fail" and depth >= 1, the decision is HandoffFail.

type Registry

type Registry map[string]Runner

Registry maps subsystem names to their runner functions.

type RunOptions

type RunOptions struct {
	Tag     string // for release subsystem
	Verbose bool
}

RunOptions holds runtime options that can be passed from CLI flags or resolved from CI context. This ensures local reproducibility — users can pass --tag v1.2.3 instead of needing CI env vars.

type Runner

type Runner func(ctx context.Context, cfg *config.Config, ciCtx *CIContext, opts RunOptions) error

Runner is the function signature for subsystem runners.