Documentation
¶
Overview ¶
Package rollback implements the `cascade rollback` command: explicit re-promotion of a prior version or SHA to a target environment.
Rollback does not introduce a new deploy code path. It resolves a prior deployment target from existing state and then re-applies that target's SHA/version to the environment using the same state-write machinery the promote/finalize flow uses. Target resolution walks the environment's live state, then its deploy-history ring (state.<env>.previous, newest first), then the git history of the manifest.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewCommand ¶
NewCommand creates the `cascade rollback` command.
Types ¶
type HistoryReader ¶
type HistoryReader interface {
// PriorStates returns historical EnvState snapshots for env, newest first,
// excluding the current (HEAD) state. Implementations should return an
// empty slice (not an error) when no history is available.
PriorStates(env string) ([]*config.EnvState, error)
}
HistoryReader yields prior environment states recorded in the manifest's history, newest first. It exists so rollback can recover a target the live manifest has already moved past, and so tests can supply deterministic history without a git repository.
type Options ¶
type Options struct {
// ConfigPath is the manifest path. When empty, the caller is expected to
// have resolved it (e.g. via config.FindConfigFile) before constructing.
ConfigPath string
// ManifestKey is the top-level manifest key (default: config.DefaultManifestKey).
ManifestKey string
// Actor is recorded as committed_by / deployed_by on the re-promotion.
Actor string
// HistoryReader resolves prior states from manifest git history. When nil,
// a git-backed reader rooted at the manifest is used.
HistoryReader HistoryReader
}
Options configures a Rollbacker.
type Plan ¶
type Plan struct {
Environment string `json:"environment"`
Target Target `json:"target"`
// Deployable, when non-empty, scopes the rollback to a single deployable's
// per-deployable version state rather than the whole environment.
Deployable string `json:"deployable,omitempty"`
// CurrentSHA / CurrentVersion record the environment's state before the
// rollback, for operator visibility and "rollback from" reporting.
CurrentSHA string `json:"current_sha,omitempty"`
CurrentVersion string `json:"current_version,omitempty"`
// NoOp is true when the environment (or deployable) is already at the
// requested target; Apply becomes a no-op in that case.
NoOp bool `json:"no_op"`
}
Plan is the read-only result of resolving a rollback. It captures exactly what a subsequent Apply would write, without mutating any state.
type Rollbacker ¶
type Rollbacker struct {
// contains filtered or unexported fields
}
Rollbacker resolves and applies rollbacks against a manifest.
func New ¶
func New(opts Options) (*Rollbacker, error)
New constructs a Rollbacker, loading and parsing the manifest.
func (*Rollbacker) Apply ¶
func (r *Rollbacker) Apply(plan *Plan) error
Apply writes the resolved plan into the manifest and persists it, recording the actor. It is a no-op when plan.NoOp is true. Apply is the only mutating operation; Plan never writes.
func (*Rollbacker) ConfigPath ¶
func (r *Rollbacker) ConfigPath() string
ConfigPath returns the resolved manifest path the Rollbacker reads and writes. The finalize subcommand uses it to commit the post-rollback state back to the trunk branch.
func (*Rollbacker) DeployNames ¶
func (r *Rollbacker) DeployNames() []string
DeployNames returns the names of the deploys declared in the manifest, in declaration order. The finalize subcommand uses it to gate the state write on each deploy job's reported result. It returns nil when no deploys are configured (a state-only, deploy-less rollback).
func (*Rollbacker) GitIdentity ¶ added in v0.5.0
func (r *Rollbacker) GitIdentity() statewrite.Identity
GitIdentity returns the commit identity for the post-rollback state write, taken from the manifest git config so an automated rollback commit is attributed to the configured bot rather than the token owner. An absent or empty git config resolves to the github-actions[bot] default.
func (*Rollbacker) Plan ¶
func (r *Rollbacker) Plan(env, to, deployable string) (*Plan, error)
Plan resolves the rollback target for env and (optionally) a single deployable, without mutating any state. It returns a clear error when the environment is unknown or the requested target cannot be resolved.
to is matched against both SHA and version. Matching is exact for full values and prefix-based for SHAs (so a short SHA resolves to the recorded full SHA). When to is empty, Plan resolves the previous version (the N-1 entry in the deploy-history ring, or the newest distinct prior state from manifest history when the ring has no distinct entry).
type Target ¶
type Target struct {
SHA string `json:"sha"`
Version string `json:"version,omitempty"`
// Source explains how the target was resolved, e.g. "state" or
// "git-history". Useful for operator-facing output and tests.
Source string `json:"source"`
// Deployable is set when the target was scoped to a single deployable.
Deployable string `json:"deployable,omitempty"`
}
Target describes a resolved rollback destination: the SHA and version a re-promotion should re-apply, plus where it was found (for human output).
Source Files