promote

package
v0.2.0-rc.20 Latest Latest
Warning

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

 Go to latest Published: Jun 11, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewCommand 

func NewCommand() *cobra.Command

NewCommand creates the promote parent command with subcommands.

Types

type EnvPromotion 

type EnvPromotion struct {
	Environment string `json:"environment"`
	SourceEnv   string `json:"source_env"`
	SHA         string `json:"sha"`
	Version     string `json:"version"`
	NeedsDeploy bool   `json:"needs_deploy"`
}

EnvPromotion describes what should happen for a single environment

type Finalizer 

type Finalizer struct {
	// contains filtered or unexported fields
}

Finalizer handles post-deployment state updates after a promotion completes. It updates the manifest state based on: - Deploy job results (from GitHub Actions) - Promotion result (from preflight output) - Release publishing status

func NewFinalizer 

func NewFinalizer(configPath, targetEnv string) (*Finalizer, error)

NewFinalizer creates a new Finalizer instance. It loads the manifest from configPath and prepares for state updates. The manifest must have the ci: key at the top level.

func NewFinalizerWithKey 

func NewFinalizerWithKey(configPath, targetEnv, manifestKey string) (*Finalizer, error)

NewFinalizerWithKey creates a Finalizer with a custom manifest key.

func (*Finalizer) CommitAndPush 

func (f *Finalizer) CommitAndPush() error

CommitAndPush persists the manifest changes back to the trunk branch.

On real GitHub the write goes through the Contents REST API (via the gh CLI): API-created commits are signed by GitHub (shown as Verified) and, when made with a bypass-capable token, update the trunk even when a required status check protects the branch. In the act/gitea e2e environment there is no GitHub API, so the change is committed and pushed with plain git. The environment is detected exactly as the generated dispatch steps do, by GITHUB_SERVER_URL != https://github.com.

Note: We skip git pull because the workflow just checked out the repo, so it should already be at the latest state. The finalize job runs after all deploy jobs complete, and they don't modify the manifest.

func (*Finalizer) Run 

func (f *Finalizer) Run() error

Run executes the finalization logic: 1. Updates environment state for all promoted environments 2. Updates per-deploy state for successful deploys only 3. Updates latest_release state if publishing a release 4. Writes the updated manifest back to disk

Note: This updates the in-memory state and writes to disk. Call this only when you want to persist changes.

func (*Finalizer) SetActor 

func (f *Finalizer) SetActor(actor string)

SetActor sets the actor performing the finalization (for audit trail).

func (*Finalizer) SetDeployResult 

func (f *Finalizer) SetDeployResult(name, result string)

SetDeployResult records the result of a deploy job. Valid results: "success", "failure", "skipped", "cancelled"

func (*Finalizer) SetHeadSHA added in v0.2.0 

func (f *Finalizer) SetHeadSHA(sha string)

SetHeadSHA overrides the SHA written to state.<env>.sha during finalization. Call this when one or more callbacks declared auto_commits: true, meaning they pushed additional commits after the workflow started. Passing the post-callback HEAD ensures the recorded state matches what was actually built/deployed rather than the triggering commit.

When sha is empty (the default) the SHA from the promotion result is used unchanged, preserving existing behavior for runs without auto-committing callbacks.

func (*Finalizer) SetPromotionResult 

func (f *Finalizer) SetPromotionResult(pr *PromotionResult)

SetPromotionResult sets the promotion result from preflight output. This contains information about which environments to update and release actions.

func (*Finalizer) WriteConfig 

func (f *Finalizer) WriteConfig() error

WriteConfig writes the updated manifest back to disk. The output is wrapped in the manifest key (default: "ci") to match the expected format.

type PreflightResult 

type PreflightResult struct {
	// Mode and configuration
	Mode              PromotionMode `json:"mode"`
	Target            string        `json:"target,omitempty"`              // For cascade mode
	Force             bool          `json:"force,omitempty"`               // For default mode
	RollbackOnFailure bool          `json:"rollback_on_failure,omitempty"` // Revert successful deploys if any fails

	// Source/target info
	SourceEnv     string `json:"source_env"`
	TargetEnv     string `json:"target_env"`
	SourceSHA     string `json:"source_sha"`
	SourceVersion string `json:"source_version"`

	// Rollback SHA (target env's current SHA before promotion - what we revert to on failure)
	RollbackSHA string `json:"rollback_sha,omitempty"`

	// Changelog comparison point (SHA of first target env before promotion)
	ChangelogBaseSHA string `json:"changelog_base_sha"`

	// Environments to update
	EnvsToUpdate []string `json:"envs_to_update"`
	SkippedEnvs  []string `json:"skipped_envs"`

	// Deploy decisions
	DeploysToRun         []string `json:"deploys_to_run"`          // Local deploys to run
	ExternalDeploysToRun []string `json:"external_deploys_to_run"` // External deploys to run

	// Release info
	IsPrereleaseEnv bool   `json:"is_prerelease_env"`
	IsFinalEnv      bool   `json:"is_final_env"`
	IsCascade       bool   `json:"is_cascade"`
	ReleaseAction   string `json:"release_action"`

	// Full-pass prod deployment (separate from cascade)
	HasProdDeployment bool   `json:"has_prod_deployment"`
	ProdSHA           string `json:"prod_sha"`
	ProdVersion       string `json:"prod_version"`

	// Breaking changes
	HasBreaking       bool   `json:"has_breaking"`
	CanProceed        bool   `json:"can_proceed"`
	BreakingBlockedAt string `json:"breaking_blocked_at,omitempty"` // The transition that was blocked

	// Full promotion result for downstream use
	PromotionResult *PromotionResult `json:"promotion_result"`
}

PreflightResult contains all outputs needed by the workflow

type Preflighter 

type Preflighter struct {
	// contains filtered or unexported fields
}

Preflighter handles preflight validation and planning

func NewPreflighter 

func NewPreflighter(opts PreflighterOptions) *Preflighter

NewPreflighter creates a new Preflighter instance

func (*Preflighter) Run 

func (p *Preflighter) Run() (*PreflightResult, error)

Run executes the preflight checks and returns the result

func (*Preflighter) SetDeployCheck 

func (p *Preflighter) SetDeployCheck(name string, include bool)

SetDeployCheck sets whether a deploy should be included

type PreflighterOptions 

type PreflighterOptions struct {
	Config            *config.CICDFile
	Mode              PromotionMode
	Target            string // For cascade mode (e.g., "dev-to-prod")
	Force             bool   // For default mode
	BaseDir           string
	DeploysFilter     []string // Specific deploys to include (empty = all)
	RollbackOnFailure bool     // Revert successful deploys if any fails
}

PreflighterOptions configures the Preflighter

type Promoter 

type Promoter struct {
	// contains filtered or unexported fields
}

Promoter handles promotion logic

func NewPromoter 

func NewPromoter(opts PromoterOptions) (*Promoter, error)

NewPromoter creates a new Promoter

func (*Promoter) CommitAndPush 

func (p *Promoter) CommitAndPush(message string) error

CommitAndPush commits the state change and pushes to remote

func (*Promoter) Promote 

func (p *Promoter) Promote(mode PromotionMode, target string) (*PromotionResult, error)

Promote executes a promotion and returns the result mode: "default" for sequential single-step, "cascade" for atomic multi-step target: for cascade mode, the target (e.g., "dev-to-prod")

type PromoterOptions 

type PromoterOptions struct {
	ConfigPath string
	DryRun     bool
	Actor      string
	Force      bool // For default mode: continue on failure
}

PromoterOptions configures the Promoter

type PromotionMode 

type PromotionMode string

PromotionMode defines how the promotion operates 

const (
	// ModeDefault promotes each environment to its immediate next (sequential)
	// Supports force flag to continue on failure
	ModeDefault PromotionMode = "default"

	// ModeCascade promotes source through all intermediate envs to target (atomic)
	// Bails entirely on any failure - no partial state updates
	ModeCascade PromotionMode = "cascade"
)

type PromotionResult 

type PromotionResult struct {
	Success        bool           `json:"success"`
	Mode           PromotionMode  `json:"mode"`
	Target         string         `json:"target,omitempty"`       // Target for cascade mode (e.g., "dev-to-prod")
	Force          bool           `json:"force,omitempty"`        // Force flag for default mode
	IsCascade      bool           `json:"is_cascade"`             // True for cascade mode
	Promotions     []EnvPromotion `json:"promotions"`             // Successful promotions
	FailedEnvs     []string       `json:"failed_envs,omitempty"`  // Envs that failed (default+force)
	SkippedEnvs    []string       `json:"skipped_envs,omitempty"` // Envs skipped due to no-op
	FinalEnv       string         `json:"final_env,omitempty"`
	ReleaseAction  string         `json:"release_action,omitempty"` // "prerelease", "publish", or ""
	ReleaseData    *ReleaseData   `json:"release_data,omitempty"`
	ProdDeployment *EnvPromotion  `json:"prod_deployment,omitempty"`
	Error          string         `json:"error,omitempty"`
}

PromotionResult is the output of a promotion operation

func (*PromotionResult) ToJSON 

func (r *PromotionResult) ToJSON() string

ToJSON returns the result as JSON

type ReleaseData 

type ReleaseData struct {
	SHA        string `json:"sha"`
	RCVersion  string `json:"rc_version"`  // e.g., v1.0.0-rc.0
	SemVersion string `json:"sem_version"` // e.g., v1.0.0
}

ReleaseData contains info for release management

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.