config

package
v0.3.0-rc.22 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const (
	RolloutTypeDefault   = "default"
	RolloutTypeRolling   = "rolling"
	RolloutTypeCanary    = "canary"
	RolloutTypeBlueGreen = "blue_green"
)

Rollout type constants.

View Source 
const (
	DispatchInputTypeString      = "string"
	DispatchInputTypeBoolean     = "boolean"
	DispatchInputTypeChoice      = "choice"
	DispatchInputTypeEnvironment = "environment"
	DispatchInputTypeNumber      = "number"
)

Dispatch input type constants (GHA dispatch input types).

View Source 
const (
	PinModeTag = "tag"
	PinModeSHA = "sha"
)

Pin mode constants.

View Source 
const (
	TelemetryAdapterNone    = "none"
	TelemetryAdapterDatadog = "datadog"
)

Telemetry adapter constants. The vendor stays an Adapter value behind the seam; no vendor client is wired into core. These name the known adapter values for documentation and future use and are not enforced as an enum (an arbitrary adapter string parses today and must keep parsing).

View Source 
const (
	// EnvBranchPolicyProtected restricts deployments to protected branches.
	EnvBranchPolicyProtected = "protected"
	// EnvBranchPolicyCustom restricts deployments to branches and tags matching
	// the configured patterns.
	EnvBranchPolicyCustom = "custom"
	// EnvBranchPolicyAll places no branch restriction on deployments.
	EnvBranchPolicyAll = "all"
)

Environment branch-policy mode constants. They map onto GitHub's deployment_branch_policy model: protected_branches, custom_branch_policies, or null (all branches).

View Source 
const (
	DeployTargetModeDispatch = "dispatch"
	DeployTargetModeGitOps   = "gitops"
)

Deploy target mode constants.

View Source 
const (
	// CurrentSchemaVersion is the highest schema version this CLI understands
	// and the version assumed for manifests that omit schema_version.
	CurrentSchemaVersion = 1
	// MinSchemaVersion is the oldest schema version this CLI still reads.
	// Manifests below this are rejected with a pointer to the migration table.
	MinSchemaVersion = 1
)

Schema version bounds. schema_version declares which generation of the manifest schema a config is written for. It is a single monotonic integer (a "schema major"), not a semver string: additive changes (new optional fields, new enum values) never bump it, because old manifests keep working and the CLI fills defaults. Only a breaking change (a removed field, a changed default's behavior, a re-typed field) bumps it, with a matching migration entry in CHANGELOG.md. See docs/versioning.md for the policy.

View Source 
const (
	GitModeDefault  = "default"  // Use github-actions[bot]
	GitModeCustom   = "custom"   // Use configured user_name/user_email
	GitModeExternal = "external" // Skip git config, assume pre-configured
)

GitMode constants

View Source 
const (
	RunPolicyDefault = "default"
	RunPolicyAlways  = "always"
	RunPolicyForce   = "force"
)

RunPolicy constants

View Source 
const (
	OnFailureAbort    = "abort"
	OnFailureContinue = "continue"
)

OnFailure constants

View Source 
const (
	CallbackTypeBuild    = "build"
	CallbackTypeDeploy   = "deploy"
	CallbackTypeValidate = "validate"
	CallbackTypeExternal = "external" // External repo deploy
)

Callback type constants

View Source 
const DefaultCLIVersion = "v0.1.0"

DefaultCLIVersion is the immutable cascade release tag pinned into generated workflows when cli_version is unset (or set to the mutable "latest"). Bump this with each cascade release so generated pipelines track the newest stable tag.

View Source 
const DefaultManifestFile = ".github/manifest.yaml"

DefaultManifestFile is the default manifest file path

View Source 
const DefaultManifestKey = "ci"

DefaultManifestKey is the default key used in the manifest file

View Source 
const MaxPreviousSnapshots = 10

MaxPreviousSnapshots bounds the per-environment deploy-history ring (state.<env>.previous). Once the ring reaches this length the oldest snapshot is dropped as a newer one is prepended, so the ring records at most this many prior states, newest first.

View Source 
const MaxWaitTimerMinutes = 43200

MaxWaitTimerMinutes is the largest wait_timer GitHub accepts: 43200 minutes (30 days).

Variables

This section is empty.

Functions

func DisplayName 

func DisplayName(callbackType, name string) string

DisplayName returns the display name for a callback (e.g., "Build (app)", "Deploy (app)")

func FindConfigFile 

func FindConfigFile(baseDir string) string

FindConfigFile finds the manifest file path. If baseDir is empty, uses current working directory. Returns the default path if no file is found.

func FindManifestFile 

func FindManifestFile(baseDir string) string

FindManifestFile looks for manifest.yaml or manifest.yml in the given directory. Returns the path to the found file, or empty string if not found.

func GetBuildNames 

func GetBuildNames(cfg *TrunkConfig) []string

GetBuildNames returns a list of all build names

func GetDeployNames 

func GetDeployNames(cfg *TrunkConfig) []string

GetDeployNames returns a list of all deploy names

func IsExternalWorkflow 

func IsExternalWorkflow(workflowPath string) bool

IsExternalWorkflow returns true if the workflow path references an external repo External paths have format: "org/repo/.github/workflows/file.yaml@ref" Local paths start with "." or ".github/"

func IsNegationPattern added in v0.2.0 

func IsNegationPattern(pattern string) bool

IsNegationPattern reports whether a trigger pattern is an exclusion pattern (a leading "!"). Exclusion patterns mirror GitHub Actions' paths-ignore semantics: a file that matches an exclusion does not count as a trigger even if it also matches a positive pattern.

func JobID 

func JobID(callbackType, name string) string

JobID returns the prefixed job ID for a callback (e.g., "build-app", "deploy-app")

func MatchAnyTrigger added in v0.2.0 

func MatchAnyTrigger(patterns []string, changedFiles []string) bool

MatchAnyTrigger reports whether any of the changed files is a trigger under the supplied pattern list (negation-aware via MatchTrigger). An empty pattern list means "always triggered". This is the shared evaluator that the CLI-side change detection uses so it agrees with the emitted GitHub Actions paths filter, which is generated verbatim from the same pattern list.

func MatchGlobPattern added in v0.2.0 

func MatchGlobPattern(pattern, path string) bool

MatchGlobPattern reports whether a single glob pattern matches a path. A leading "!" is stripped before matching, so the helper reports whether the bare glob matches; negation as an exclusion is applied at the pattern-list level by MatchTrigger. Supports "*" (single segment), "**" (any number of segments) and "?" (single character), matching the grammar used by the emitted GitHub Actions paths filter.

func MatchTrigger added in v0.2.0 

func MatchTrigger(patterns []string, file string) bool

MatchTrigger reports whether a single changed file path matches the supplied trigger pattern list, honouring negation ("!"-prefixed) patterns.

Semantics (frozen v1 contract, GitHub Actions paths/paths-ignore combined behaviour): a file matches when it matches at least one positive pattern AND matches no negation pattern. This is intentionally order-independent: a path is a trigger if and only if it satisfies some positive include and is not excluded by any "!" pattern. When the pattern list contains only negation patterns (no positives), any file not excluded counts as a match, matching GitHub Actions, which treats a negation-only list like paths-ignore.

func NewCommand 

func NewCommand() *cobra.Command

NewCommand creates the parse-config command

func OutputKey 

func OutputKey(jobID string) string

OutputKey converts a job ID to an output-safe key by using underscores instead of hyphens GitHub Actions expressions interpret hyphens as subtraction, so we use underscores for output keys Example: "build-app" -> "build_app"

func Validate 

func Validate(cfg *TrunkConfig) []string

Validate checks the configuration for errors

Types

type AppTokenSource added in v0.3.0 

type AppTokenSource struct {
	AppID      string `yaml:"app_id,omitempty" json:"app_id,omitempty"`
	PrivateKey string `yaml:"private_key,omitempty" json:"private_key,omitempty"`
}

AppTokenSource backs a token seam with a GitHub App identity. At run time the generator emits an actions/create-github-app-token step that exchanges these for a short-lived installation token; the consuming steps reference that minted token instead of a static secret. AppID and PrivateKey are SECRET REFERENCES (a secrets/vars expression or bare secret name), never raw key material: the App private key is stored only as a GitHub secret.

type ArtifactConfig 

type ArtifactConfig struct {
	Name     string `yaml:"name" json:"name"`                             // Artifact identifier (e.g., "linux-amd64", "checksums")
	Path     string `yaml:"path" json:"path"`                             // Glob pattern for files to include (e.g., "dist/*.tar.gz")
	Required bool   `yaml:"required,omitempty" json:"required,omitempty"` // Fail release if artifact missing (default: true)
}

ArtifactConfig defines a release artifact produced by a build Build workflows should upload artifacts with name: release-{build-name}-{artifact-name}

type BlueGreenConfig added in v0.2.0 

type BlueGreenConfig struct {
	// Switch is a workflow path that performs the blue/green cutover.
	Switch string `yaml:"switch,omitempty" json:"switch,omitempty"`
}

BlueGreenConfig is the reserved blue/green rollout sub-block.

type BuildConfig 

type BuildConfig struct {
	Name           string                            `yaml:"name" json:"name"`
	Workflow       string                            `yaml:"workflow,omitempty" json:"workflow,omitempty"`
	Run            string                            `yaml:"run,omitempty" json:"run,omitempty"`     // rejected: inline run is no longer supported; use workflow:
	Shell          string                            `yaml:"shell,omitempty" json:"shell,omitempty"` // rejected: inline shell is no longer supported; use workflow:
	Triggers       []string                          `yaml:"triggers" json:"triggers"`
	DependsOn      []string                          `yaml:"depends_on,omitempty" json:"depends_on,omitempty"`
	StateTags      []string                          `yaml:"state_tags,omitempty" json:"state_tags,omitempty"`
	Artifacts      []ArtifactConfig                  `yaml:"artifacts,omitempty" json:"artifacts,omitempty"`
	RunPolicy      string                            `yaml:"run_policy,omitempty" json:"run_policy,omitempty"`
	OnFailure      string                            `yaml:"on_failure,omitempty" json:"on_failure,omitempty"`
	Retries        int                               `yaml:"retries,omitempty" json:"retries,omitempty"`
	TimeoutMinutes int                               `yaml:"timeout_minutes,omitempty" json:"timeout_minutes,omitempty"` // Job-level timeout-minutes (omits when 0)
	Inputs         map[string]interface{}            `yaml:"inputs,omitempty" json:"inputs,omitempty"`
	EnvInputs      map[string]map[string]interface{} `yaml:"env_inputs,omitempty" json:"env_inputs,omitempty"`

	// v1 reserved-shape per-callback fields (parse + structural validation only).
	Secrets             *SecretsConfig       `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	Permissions         map[string]string    `yaml:"permissions,omitempty" json:"permissions,omitempty"`
	RunsOn              *RunsOn              `yaml:"runs_on,omitempty" json:"runs_on,omitempty"`
	Concurrency         *ConcurrencyConfig   `yaml:"concurrency,omitempty" json:"concurrency,omitempty"`
	Matrix              *MatrixConfig        `yaml:"matrix,omitempty" json:"matrix,omitempty"` // Build fan-out (builds only)
	OptionalDependsOn   []string             `yaml:"optional_depends_on,omitempty" json:"optional_depends_on,omitempty"`
	AutoCommits         bool                 `yaml:"auto_commits,omitempty" json:"auto_commits,omitempty"`
	PassthroughArtifact *PassthroughArtifact `yaml:"artifact,omitempty" json:"artifact,omitempty"` // GHA artifact passing within an orchestrate run (#16)
}

BuildConfig defines a build target

type BuildState 

type BuildState struct {
	SHA        string            `yaml:"sha,omitempty" json:"sha,omitempty"`
	BuiltAt    string            `yaml:"built_at,omitempty" json:"built_at,omitempty"`
	BuiltBy    string            `yaml:"built_by,omitempty" json:"built_by,omitempty"`
	ArtifactID string            `yaml:"artifact_id,omitempty" json:"artifact_id,omitempty"` // Immutable artifact identifier from build output (e.g., Docker image digest)
	Tags       map[string]string `yaml:"tags,omitempty" json:"tags,omitempty"`               // state_tags values
}

BuildState tracks the state of a single build within an environment

type CICDFile 

type CICDFile struct {
	Config        *TrunkConfig         `yaml:"config" json:"config"`
	State         map[string]*EnvState `yaml:"state,omitempty" json:"state,omitempty"`
	LatestRelease *LatestReleaseState  `yaml:"latest_release,omitempty" json:"latest_release,omitempty"`
}

CICDFile represents the .github/cicd.yaml file structure Contains both config (pipeline definition) and state (deployment tracking)

func ParseManifestBytes added in v0.2.0 

func ParseManifestBytes(data []byte, key string) (*CICDFile, error)

ParseManifestBytes parses manifest bytes with config under a specific key, mirroring ParseManifestFile without reading from disk. The manifest must have the specified key (default: "ci") at the top level. Returns an error if the key is not found. This is the entry point for reading a manifest fetched from a branch ref (for example, trunk) rather than the working tree.

func ParseManifestFile 

func ParseManifestFile(path, key string) (*CICDFile, error)

ParseManifestFile reads and parses a manifest file with config under a specific key. The manifest must have the specified key (default: "ci") at the top level. Returns an error if the key is not found.

type CanaryConfig added in v0.2.0 

type CanaryConfig struct {
	// Steps are the percent waves (for example [10, 50, 100]).
	Steps []int `yaml:"steps,omitempty" json:"steps,omitempty"`
	// Analysis is a workflow path that gates each wave.
	Analysis string `yaml:"analysis,omitempty" json:"analysis,omitempty"`
	// Percent is the single initial canary weight (1..100). RESERVED - not yet wired to generation.
	Percent int `yaml:"percent,omitempty" json:"percent,omitempty"`
	// BakeTime is the soak duration after traffic shift before promotion (Go duration string, e.g. "30m"). RESERVED - not yet wired to generation.
	BakeTime string `yaml:"bake_time,omitempty" json:"bake_time,omitempty"`
	// PromoteCallback is the local callback workflow path invoked on promotion. RESERVED - not yet wired to generation.
	PromoteCallback string `yaml:"promote_callback,omitempty" json:"promote_callback,omitempty"`
	// RollbackCallback is the local callback workflow path invoked on rollback. RESERVED - not yet wired to generation.
	RollbackCallback string `yaml:"rollback_callback,omitempty" json:"rollback_callback,omitempty"`
}

CanaryConfig is the reserved canary rollout sub-block.

type ChangelogConfig 

type ChangelogConfig struct {
	Disabled     bool   `yaml:"disabled,omitempty" json:"disabled,omitempty"`         // true = disabled
	Workflow     string `yaml:"workflow,omitempty" json:"workflow,omitempty"`         // custom changelog workflow
	Contributors bool   `yaml:"contributors,omitempty" json:"contributors,omitempty"` // true = include contributors section
}

ChangelogConfig defines changelog generation settings

type ComponentConfig added in v0.3.0 

type ComponentConfig struct {
	// Path is the subtree this component owns within the repo (reserved).
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
	// TagPrefix is the per-component version tag prefix (reserved). Empty means
	// inherit the manifest-level tag_prefix.
	TagPrefix string `yaml:"tag_prefix,omitempty" json:"tag_prefix,omitempty"`
}

ComponentConfig is the reserved per-component descriptor. Only the addressing shape is frozen in v1; richer per-component config lands post-1.0 additively.

type ComponentReleaseState added in v0.3.0 

type ComponentReleaseState struct {
	Version    string `yaml:"version,omitempty" json:"version,omitempty"`
	SHA        string `yaml:"sha,omitempty" json:"sha,omitempty"`
	ReleasedOn string `yaml:"released_on,omitempty" json:"released_on,omitempty"`
}

ComponentReleaseState is the reserved per-component published-release entry.

type ComponentState added in v0.3.0 

type ComponentState struct {
	Version     string `yaml:"version,omitempty" json:"version,omitempty"`
	SHA         string `yaml:"sha,omitempty" json:"sha,omitempty"`
	CommittedAt string `yaml:"committed_at,omitempty" json:"committed_at,omitempty"`
	CommittedBy string `yaml:"committed_by,omitempty" json:"committed_by,omitempty"`
}

ComponentState is the reserved per-component recorded-state entry.

type ConcurrencyConfig 

type ConcurrencyConfig struct {
	Group            string `yaml:"group,omitempty" json:"group,omitempty"`
	CancelInProgress bool   `yaml:"cancel_in_progress" json:"cancel_in_progress"`
}

ConcurrencyConfig overrides the default concurrency: block emitted on the generated orchestrate workflow. Defaults: group=orchestrate-${{ github.ref }}, cancel-in-progress=true. Set cancel_in_progress=false to queue runs instead of cancelling older ones.

type DeployConfig 

type DeployConfig struct {
	Name           string                            `yaml:"name" json:"name"`
	Workflow       string                            `yaml:"workflow,omitempty" json:"workflow,omitempty"`
	Run            string                            `yaml:"run,omitempty" json:"run,omitempty"`     // rejected: inline run is no longer supported; use workflow:
	Shell          string                            `yaml:"shell,omitempty" json:"shell,omitempty"` // rejected: inline shell is no longer supported; use workflow:
	Triggers       []string                          `yaml:"triggers" json:"triggers"`
	DependsOn      []string                          `yaml:"depends_on,omitempty" json:"depends_on,omitempty"`
	StateTags      []string                          `yaml:"state_tags,omitempty" json:"state_tags,omitempty"`
	SupportsDryRun bool                              `yaml:"supports_dry_run,omitempty" json:"supports_dry_run,omitempty"`
	RunPolicy      string                            `yaml:"run_policy,omitempty" json:"run_policy,omitempty"`
	OnFailure      string                            `yaml:"on_failure,omitempty" json:"on_failure,omitempty"`
	Retries        int                               `yaml:"retries,omitempty" json:"retries,omitempty"`
	TimeoutMinutes int                               `yaml:"timeout_minutes,omitempty" json:"timeout_minutes,omitempty"` // Job-level timeout-minutes (omits when 0)
	Inputs         map[string]interface{}            `yaml:"inputs,omitempty" json:"inputs,omitempty"`
	EnvInputs      map[string]map[string]interface{} `yaml:"env_inputs,omitempty" json:"env_inputs,omitempty"`

	// v1 reserved-shape per-callback fields (parse + structural validation only).
	Secrets             *SecretsConfig       `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	Permissions         map[string]string    `yaml:"permissions,omitempty" json:"permissions,omitempty"`
	RunsOn              *RunsOn              `yaml:"runs_on,omitempty" json:"runs_on,omitempty"`
	Concurrency         *ConcurrencyConfig   `yaml:"concurrency,omitempty" json:"concurrency,omitempty"`
	Rollout             *RolloutConfig       `yaml:"rollout,omitempty" json:"rollout,omitempty"` // Deploy rollout strategy (deploys only)
	DeployTarget        *DeployTarget        `yaml:"deploy_target,omitempty" json:"deploy_target,omitempty"`
	OptionalDependsOn   []string             `yaml:"optional_depends_on,omitempty" json:"optional_depends_on,omitempty"`
	AutoCommits         bool                 `yaml:"auto_commits,omitempty" json:"auto_commits,omitempty"`
	PassthroughArtifact *PassthroughArtifact `yaml:"artifact,omitempty" json:"artifact,omitempty"` // GHA artifact passing within an orchestrate run (#16)
}

DeployConfig defines a deployment target

type DeployState 

type DeployState struct {
	SHA        string            `yaml:"sha,omitempty" json:"sha,omitempty"`
	Version    string            `yaml:"version,omitempty" json:"version,omitempty"` // Version this deployable deployed (reserved-shape; independent of env-level Version)
	DeployedAt string            `yaml:"deployed_at,omitempty" json:"deployed_at,omitempty"`
	DeployedBy string            `yaml:"deployed_by,omitempty" json:"deployed_by,omitempty"`
	Tags       map[string]string `yaml:"tags,omitempty" json:"tags,omitempty"`             // state_tags values
	TargetSHA  string            `yaml:"target_sha,omitempty" json:"target_sha,omitempty"` // RESERVED - reconciled GitOps-repo HEAD SHA, so a future implementation can key promotion off it. Not yet wired.
}

DeployState tracks the state of a single deployable within an environment

type DeployTarget added in v0.2.0 

type DeployTarget struct {
	// Mode is gitops | dispatch (default: dispatch via external/notify).
	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`
	// Repo is the GitOps config repo (e.g. org/gitops-config).
	Repo string `yaml:"repo,omitempty" json:"repo,omitempty"`
	// Path is the file to mutate in the target repo.
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
	// Field is the field to bump (e.g. image.tag).
	Field string `yaml:"field,omitempty" json:"field,omitempty"`
	// Value is the value to write (may be a GHA expression).
	Value string `yaml:"value,omitempty" json:"value,omitempty"`
	// Branch is the target branch for the GitOps write (env-to-branch
	// mapping); default is the target repo's default branch.
	// RESERVED - not yet wired to generation; meaningful only when mode is gitops.
	Branch string `yaml:"branch,omitempty" json:"branch,omitempty"`
	// TrackSHA, when true, records the post-push HEAD SHA of the target repo
	// into state. RESERVED - not yet wired to generation; meaningful only when
	// mode is gitops.
	TrackSHA bool `yaml:"track_sha,omitempty" json:"track_sha,omitempty"`
}

DeployTarget is the reserved GitOps-mirror deploy variant. It complements, not replaces, the External/Notify cross-repo dispatch model.

func (*DeployTarget) GetMode added in v0.2.0 

func (d *DeployTarget) GetMode() string

GetMode returns the deploy-target mode or the default ("dispatch").

type DeploymentsConfig added in v0.3.0 

type DeploymentsConfig struct {
	// Enabled activates GitHub Deployments API reporting in the finalize job.
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// KeepPriorActive prevents GitHub from auto-inactivating prior deployments
	// for the same environment. Maps to auto_inactive:false in the Deployments API.
	// Default false relies on GitHub native auto-inactivation.
	KeepPriorActive bool `yaml:"keep_prior_active,omitempty" json:"keep_prior_active,omitempty"`
}

DeploymentsConfig configures opt-in GitHub Deployments API integration. When enabled, the finalize job creates a Deployment per target environment and reports in_progress then success/failure status after each deploy.

type DispatchInput added in v0.2.0 

type DispatchInput struct {
	// Type is one of string|boolean|choice|environment|number.
	Type string `yaml:"type,omitempty" json:"type,omitempty"`
	// Options enumerates the valid values for a choice input.
	Options []string `yaml:"options,omitempty" json:"options,omitempty"`
	// Default is the default value (any of the supported types).
	Default interface{} `yaml:"default,omitempty" json:"default,omitempty"`
	// Description is the operator-facing help text.
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	// Required marks the input as required.
	Required bool `yaml:"required,omitempty" json:"required,omitempty"`
}

DispatchInput models a single operator-facing workflow_dispatch input.

type DriftCheckConfig added in v0.3.0 

type DriftCheckConfig struct {
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	Comment bool `yaml:"comment,omitempty" json:"comment,omitempty"`
}

DriftCheckConfig is the opt-in workflow drift-check lane (#229). When Enabled, cascade emits a pull_request workflow that runs cascade verify and fails the check on drift. When Comment is also set, cascade emits the fork-safe workflow_run companion that posts the verify result as a sticky PR comment.

The companion derives the target PR number ONLY from trusted workflow_run run metadata, never from the artifact the pull_request job uploads, so a fork PR cannot redirect the comment at another PR.

type EnvState 

type EnvState struct {
	SHA         string                          `yaml:"sha,omitempty" json:"sha,omitempty"`
	Version     string                          `yaml:"version,omitempty" json:"version,omitempty"` // Semantic version tag (e.g., v1.2.3-rc.0)
	CommittedAt string                          `yaml:"committed_at,omitempty" json:"committed_at,omitempty"`
	CommittedBy string                          `yaml:"committed_by,omitempty" json:"committed_by,omitempty"`
	Builds      map[string]*BuildState          `yaml:"builds,omitempty" json:"builds,omitempty"`
	Deploys     map[string]*DeployState         `yaml:"deploys,omitempty" json:"deploys,omitempty"`
	External    map[string]*ExternalDeployState `yaml:"external,omitempty" json:"external,omitempty"` // External repo deploy states
	// Ref is the integration branch this environment tracks instead of trunk
	// (e.g., a hotfix branch). Empty means the environment tracks trunk.
	Ref string `yaml:"ref,omitempty" json:"ref,omitempty"`
	// BaseSHA is the trunk commit the integration branch diverged from.
	BaseSHA string `yaml:"base_sha,omitempty" json:"base_sha,omitempty"`
	// Patches lists the patch commit SHAs applied on top of BaseSHA.
	Patches []string `yaml:"patches,omitempty" json:"patches,omitempty"`
	// Previous is the per-environment deploy-history ring (#23): snapshots of
	// prior env states, newest first, bounded to MaxPreviousSnapshots. Populated
	// on every state transition via PushPreviousSnapshot.
	Previous []EnvStateSnapshot `yaml:"previous,omitempty" json:"previous,omitempty"`
	// Components is the reserved per-component state slot (#176): per-component
	// version/sha records keyed by component name. Reserved-shape only.
	Components map[string]*ComponentState `yaml:"components,omitempty" json:"components,omitempty"`
}

EnvState tracks the state of a single environment

func (*EnvState) IsDiverged added in v0.2.0 

func (s *EnvState) IsDiverged() bool

IsDiverged reports whether the environment is on an integration branch rather than tracking trunk: true when it has a custom Ref or has Patches applied.

func (*EnvState) PushPreviousSnapshot added in v0.2.0 

func (s *EnvState) PushPreviousSnapshot(newSHA string)

PushPreviousSnapshot records the environment's current (outgoing) state into the deploy-history ring before the env pointer is advanced to newSHA. Callers invoke it just before overwriting SHA/Version/CommittedAt/CommittedBy, so the snapshot captures the state that is about to be replaced.

It is a no-op when there is no prior state to record (s.SHA == "") or when the environment is not actually transitioning (s.SHA == newSHA). Otherwise it prepends a snapshot of {SHA, Version, CommittedAt, CommittedBy} so the ring is ordered newest first, then caps the ring at MaxPreviousSnapshots by dropping the oldest entries. It is safe to call when s.Previous is nil.

type EnvStateSnapshot added in v0.2.0 

type EnvStateSnapshot struct {
	SHA         string `yaml:"sha,omitempty" json:"sha,omitempty"`
	Version     string `yaml:"version,omitempty" json:"version,omitempty"`
	CommittedAt string `yaml:"committed_at,omitempty" json:"committed_at,omitempty"`
	CommittedBy string `yaml:"committed_by,omitempty" json:"committed_by,omitempty"`
}

EnvStateSnapshot is a single prior env-state entry in the deploy-history ring (state.<env>.previous).

type EnvironmentConfig added in v0.2.0 

type EnvironmentConfig struct {
	// GHAEnvironment maps this env to a GitHub Environment (deployment records,
	// required reviewers, wait timers, env-scoped secrets).
	GHAEnvironment string `yaml:"gha_environment,omitempty" json:"gha_environment,omitempty"`
	// RequiredReviewers lists the user or team slugs that may approve a
	// deployment to this environment. These are slugs (for example "octocat" or
	// "team/ops"), not GitHub numeric IDs: the Environments REST API requires a
	// numeric reviewer id, so the emit command surfaces these slugs as operator
	// guidance to resolve rather than as a directly-appliable reviewers array.
	RequiredReviewers []string `yaml:"required_reviewers,omitempty" json:"required_reviewers,omitempty"`
	// WaitTimer is the delay, in minutes, before a job targeting this
	// environment runs. GitHub allows an integer between 0 and 43200 (30 days).
	WaitTimer int `yaml:"wait_timer,omitempty" json:"wait_timer,omitempty"`
	// BranchPolicy selects which branches may deploy to this environment. It
	// maps to GitHub's deployment_branch_policy model: "protected" (only
	// protected branches), "custom" (only branches matching BranchPatterns or
	// tags matching TagPatterns), or "all" (no restriction). Empty means
	// unspecified, which the emit command treats as "all".
	BranchPolicy string `yaml:"branch_policy,omitempty" json:"branch_policy,omitempty"`
	// BranchPatterns lists branch name patterns allowed to deploy when
	// BranchPolicy is "custom". Each pattern is created via the Environments
	// deployment-branch-policies API. Meaningful only when BranchPolicy is
	// "custom".
	BranchPatterns []string `yaml:"branch_patterns,omitempty" json:"branch_patterns,omitempty"`
	// TagPatterns lists tag name patterns allowed to deploy when BranchPolicy is
	// "custom". Meaningful only when BranchPolicy is "custom".
	TagPatterns []string `yaml:"tag_patterns,omitempty" json:"tag_patterns,omitempty"`
	// Secrets lists the EXPECTED env-scoped secret NAMES for this environment.
	// These are names only: cascade never stores or emits secret values. The
	// operator creates the named secrets out of band.
	Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	// Variables lists the EXPECTED env-scoped variable NAMES for this
	// environment. Names only, never values; the operator creates them out of
	// band.
	Variables []string `yaml:"variables,omitempty" json:"variables,omitempty"`
	// EnvironmentURL is the URL of the deployed environment, reported to GitHub Deployments API status updates.
	EnvironmentURL string `yaml:"environment_url,omitempty" json:"environment_url,omitempty"`
}

EnvironmentConfig is the per-environment settings block, keyed by env name under config.environment_config. environments stays the ordered source of truth for env names; this block carries per-env settings without fanning names into multiple list fields.

All fields are optional and additive: a manifest that omits them, or omits environment_config entirely, is valid and unchanged. The protection fields (required reviewers, wait timer, branch policy) and the expected secret and variable names map onto GitHub's Environments REST API so that the "cascade environments" command can emit an operator-appliable config file. cascade emits that file; the operator applies it (gh api / Terraform). cascade never calls the GitHub API.

type ExternalDeployConfig 

type ExternalDeployConfig struct {
	Name     string   `yaml:"name" json:"name"`                             // Deploy identifier (e.g., "cdk")
	Workflow string   `yaml:"workflow,omitempty" json:"workflow,omitempty"` // Workflow path - local (.github/...) or external (org/repo/.github/...@ref)
	Run      string   `yaml:"run,omitempty" json:"run,omitempty"`           // rejected: inline run is no longer supported; use workflow:
	Shell    string   `yaml:"shell,omitempty" json:"shell,omitempty"`       // rejected: inline shell is no longer supported; use workflow:
	Triggers []string `yaml:"triggers,omitempty" json:"triggers,omitempty"` // File patterns for change detection

	// v1 reserved-shape per-callback fields (parse + structural validation only).
	// Applied by extension to external deploys per spec §2.
	Secrets           *SecretsConfig     `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	Permissions       map[string]string  `yaml:"permissions,omitempty" json:"permissions,omitempty"`
	RunsOn            *RunsOn            `yaml:"runs_on,omitempty" json:"runs_on,omitempty"`
	Concurrency       *ConcurrencyConfig `yaml:"concurrency,omitempty" json:"concurrency,omitempty"`
	Rollout           *RolloutConfig     `yaml:"rollout,omitempty" json:"rollout,omitempty"`
	DeployTarget      *DeployTarget      `yaml:"deploy_target,omitempty" json:"deploy_target,omitempty"`
	OptionalDependsOn []string           `yaml:"optional_depends_on,omitempty" json:"optional_depends_on,omitempty"`
	AutoCommits       bool               `yaml:"auto_commits,omitempty" json:"auto_commits,omitempty"`

	// OnUpdate declares what the receiver does when this external slot is
	// recorded with a new version. When unset the receiver is record-only, the
	// historical default, and no deploy is run.
	OnUpdate *OnUpdateConfig `yaml:"on_update,omitempty" json:"on_update,omitempty"`
}

ExternalDeployConfig defines a deployable from an external repository

type ExternalDeployState 

type ExternalDeployState struct {
	Repo       string            `yaml:"repo" json:"repo"`                                   // Source repo (e.g., "org/cdk-infra")
	SHA        string            `yaml:"sha,omitempty" json:"sha,omitempty"`                 // Commit SHA from external repo
	Version    string            `yaml:"version,omitempty" json:"version,omitempty"`         // Version from external repo
	DeployedAt string            `yaml:"deployed_at,omitempty" json:"deployed_at,omitempty"` // Last deployment timestamp
	DeployedBy string            `yaml:"deployed_by,omitempty" json:"deployed_by,omitempty"` // Actor who triggered deploy
	Artifacts  map[string]string `yaml:"artifacts,omitempty" json:"artifacts,omitempty"`     // Artifact references (e.g., image_tag)
}

ExternalDeployState tracks the state of an external deployable within an environment

type ExternalRepoConfig 

type ExternalRepoConfig struct {
	Repo    string                 `yaml:"repo" json:"repo"`                   // e.g., "org/cdk-infra"
	Ref     string                 `yaml:"ref,omitempty" json:"ref,omitempty"` // Branch/tag reference (default: trunk_branch)
	Deploys []ExternalDeployConfig `yaml:"deploys" json:"deploys"`             // Deployables from this repo
}

ExternalRepoConfig defines an external repository that this primary coordinates

func (*ExternalRepoConfig) GetRef 

func (e *ExternalRepoConfig) GetRef(trunkBranch string) string

GetExternalRef returns the ref for an external repo config, defaulting to trunk_branch

type ExtraTriggers added in v0.2.0 

type ExtraTriggers struct {
	// Schedule holds cron schedule entries.
	Schedule []ScheduleEntry `yaml:"schedule,omitempty" json:"schedule,omitempty"`
	// RepositoryDispatch enables the repository_dispatch trigger.
	RepositoryDispatch *RepositoryDispatchTrigger `yaml:"repository_dispatch,omitempty" json:"repository_dispatch,omitempty"`
	// WorkflowRun enables the workflow_run trigger.
	WorkflowRun *WorkflowRunTrigger `yaml:"workflow_run,omitempty" json:"workflow_run,omitempty"`
	// MergeGroup, when present (even empty), wires the GHA merge-queue trigger.
	// The validation lane behavior lives in the separate merge_queue: block.
	MergeGroup *MergeGroupTrigger `yaml:"merge_group,omitempty" json:"merge_group,omitempty"`
}

ExtraTriggers models config-level non-push trigger types.

type GitConfig 

type GitConfig struct {
	Mode         string `yaml:"mode,omitempty" json:"mode,omitempty"`                     // default, custom, external
	UserName     string `yaml:"user_name,omitempty" json:"user_name,omitempty"`           // git user.name (if mode=custom)
	UserEmail    string `yaml:"user_email,omitempty" json:"user_email,omitempty"`         // git user.email (if mode=custom)
	GPGKeyID     string `yaml:"gpg_key_id,omitempty" json:"gpg_key_id,omitempty"`         // GPG key ID for signing
	GPGKeySecret string `yaml:"gpg_key_secret,omitempty" json:"gpg_key_secret,omitempty"` // secret name containing GPG key
}

GitConfig defines git identity and signing configuration

type LatestReleaseState 

type LatestReleaseState struct {
	Version    string `yaml:"version,omitempty" json:"version,omitempty"`         // e.g., v1.2.0
	SHA        string `yaml:"sha,omitempty" json:"sha,omitempty"`                 // Commit SHA
	ReleasedOn string `yaml:"released_on,omitempty" json:"released_on,omitempty"` // ISO 8601 timestamp
	ReleasedBy string `yaml:"released_by,omitempty" json:"released_by,omitempty"` // GitHub actor who triggered release
	// Components is the reserved per-component latest-release record (#176).
	Components map[string]*ComponentReleaseState `yaml:"components,omitempty" json:"components,omitempty"`
}

LatestReleaseState tracks the most recent published release

type MatrixConfig added in v0.2.0 

type MatrixConfig struct {
	// Dimensions are the cross-product axes (e.g. os: [...], arch: [...]).
	Dimensions map[string][]string `yaml:"dimensions,omitempty" json:"dimensions,omitempty"`
	// MaxParallel caps concurrent matrix legs (0 = GHA default).
	MaxParallel int `yaml:"max_parallel,omitempty" json:"max_parallel,omitempty"`
	// FailFast is a pointer so "unset" differs from "false". When nil the
	// generator applies its default (GHA's true for matrix builds).
	FailFast *bool `yaml:"fail_fast,omitempty" json:"fail_fast,omitempty"`
}

MatrixConfig models build fan-out (matrix:) on a build callback. Builds only.

type MergeGroupTrigger added in v0.2.0 

type MergeGroupTrigger struct{}

MergeGroupTrigger wires the raw merge_group trigger. Presence enables it; the struct is intentionally empty for v1 (additive fields may arrive later).

type MergeQueueConfig added in v0.2.0 

type MergeQueueConfig struct {
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
}

MergeQueueConfig is the opt-in merge-queue validation lane (#42). The raw trigger lives separately under extra_triggers.merge_group.

type NotifyConfig 

type NotifyConfig struct {
	Repo     string `yaml:"repo" json:"repo"`                             // Primary repo to notify (e.g., "org/my-backend")
	Workflow string `yaml:"workflow,omitempty" json:"workflow,omitempty"` // Workflow to dispatch (default: "external-update.yaml")
	Token    string `yaml:"token,omitempty" json:"token,omitempty"`       // Secret name for cross-repo dispatch (default: "PRIMARY_REPO_TOKEN")
}

NotifyConfig defines how a satellite repo notifies its primary after dev deploys

func (*NotifyConfig) GetToken 

func (n *NotifyConfig) GetToken() string

GetToken returns the token secret expression or default

func (*NotifyConfig) GetWorkflow 

func (n *NotifyConfig) GetWorkflow() string

GetWorkflow returns the notify workflow name or default

type OnUpdateConfig added in v0.2.0 

type OnUpdateConfig struct {
	// Deploy, when set, runs a scoped deploy in the same receiver run after the
	// slot is recorded. When nil the receiver remains record-only.
	Deploy *OnUpdateDeploy `yaml:"deploy,omitempty" json:"deploy,omitempty"`
}

OnUpdateConfig declares what the receiver does when this external slot is recorded with a new version. Absent => record-only (the historical default).

type OnUpdateDeploy added in v0.2.0 

type OnUpdateDeploy struct {
	// Workflow is the reusable-workflow path to run as the scoped deploy, mirroring
	// deploys[].workflow (local ".github/workflows/x.yaml" or "org/repo/.github/...@ref").
	Workflow string `yaml:"workflow" json:"workflow"`
}

OnUpdateDeploy declares a scoped deploy run in the same receiver run after the slot is recorded, scoped to the updated component only.

type PRPreviewConfig added in v0.2.0 

type PRPreviewConfig struct {
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	Comment bool `yaml:"comment,omitempty" json:"comment,omitempty"`
}

PRPreviewConfig is the opt-in read-only PR plan-preview lane (#40).

type ParseResult 

type ParseResult struct {
	Config      TrunkConfig `json:"config"`
	BuildNames  []string    `json:"build_names"`
	DeployNames []string    `json:"deploy_names"`
	Valid       bool        `json:"valid"`
	Errors      []string    `json:"errors,omitempty"`
	Warnings    []string    `json:"warnings,omitempty"` // Non-fatal advisories (e.g. omitted/older schema_version)
}

ParseResult is the output of parse-config command

type PassthroughArtifact added in v0.2.0 

type PassthroughArtifact struct {
	// Upload is the path glob to upload after this job completes (via upload-artifact).
	// The artifact is named "build-{this-job-name}".
	Upload string `yaml:"upload,omitempty" json:"upload,omitempty"`
	// Downloads lists the names of upstream build jobs whose artifacts to download
	// before this job runs (each downloads "build-{name}").
	Downloads []string `yaml:"downloads,omitempty" json:"downloads,omitempty"`
}

PassthroughArtifact declares GHA artifacts passed between jobs within a single orchestrate run via actions/upload-artifact and actions/download-artifact. The uploaded artifact is named "build-{build-name}" so consumers can reference it.

Example: 

builds:
  - name: compile
    artifact:
      upload: dist/
  - name: sign
    depends_on: [compile]
    artifact:
      downloads: [compile]   # downloads "build-compile" before running
      upload: dist-signed/

type PromotionMode 

type PromotionMode string

PromotionMode represents the promotion mode 

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

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

type PromotionOption 

type PromotionOption struct {
	Name         string   `json:"name"`           // e.g., "dev-to-uat", "dev-to-prod"
	FromEnv      string   `json:"from_env"`       // source environment
	ToEnv        string   `json:"to_env"`         // target environment
	EnvsToUpdate []string `json:"envs_to_update"` // all envs between source and target (inclusive of target)
	IsPrerelease bool     `json:"is_prerelease"`  // triggers draft→prerelease (env before release marker)
	IsRelease    bool     `json:"is_release"`     // triggers prerelease→released (includes release marker)
	IncludesProd bool     `json:"includes_prod"`  // includes prod deployment
}

PromotionOption represents a cascade promotion target for manual mode

type PublishConfig 

type PublishConfig struct {
	Workflow string `yaml:"workflow" json:"workflow"` // Path to the reusable workflow (e.g., ".github/workflows/publish.yaml")
}

PublishConfig defines a publish callback invoked after a release is published. The publish workflow receives one matrix entry per configured build, carrying the build's metadata so the user can retag artifacts in their registries.

Inputs passed to the publish workflow per build:

  • build_name: name of the build (e.g., "app")
  • old_version: the RC version that was published (e.g., "v1.0.0-rc.2")
  • new_version: the final semver version (e.g., "v1.0.0")
  • sha: the git commit SHA of the built artifact
  • artifact_id: the immutable artifact identifier stored from the build job output (e.g., Docker image digest "sha256:abc..."). Empty if the build did not emit an artifact_id output.

type ReleaseConfig 

type ReleaseConfig struct {
	Disabled bool   `yaml:"disabled,omitempty" json:"disabled,omitempty"` // true = disabled
	Tag      string `yaml:"tag,omitempty" json:"tag,omitempty"`           // callback.output reference for external releases

	// Workflow is the optional reusable-workflow path dispatched after a final
	// release is published, for example to build and attach release binaries to
	// the published release (e.g. ".github/workflows/release-build.yaml"). When
	// unset, no release-build dispatch is emitted and publishing a release does
	// not trigger any follow-on workflow.
	Workflow string `yaml:"workflow,omitempty" json:"workflow,omitempty"`

	// VersionOverrides reserves the addressing pointer for maintainer-committed
	// version-intent override files. RESERVED - parse + structural validation
	// only; no generator/state/runtime behavior. Absent by default.
	VersionOverrides *VersionOverridesConfig `yaml:"version_overrides,omitempty" json:"version_overrides,omitempty"`
}

ReleaseConfig defines release management settings

type RepositoryDispatchTrigger added in v0.2.0 

type RepositoryDispatchTrigger struct {
	Types []string `yaml:"types,omitempty" json:"types,omitempty"`
}

RepositoryDispatchTrigger configures the repository_dispatch trigger.

type RollbackConfig added in v0.3.0 

type RollbackConfig struct {
	// RepositoryDispatch opts the rollback workflow into a repository_dispatch
	// trigger. Reuses the shared RepositoryDispatchTrigger shape so the event
	// types are configured the same way as extra_triggers.repository_dispatch.
	RepositoryDispatch *RepositoryDispatchTrigger `yaml:"repository_dispatch,omitempty" json:"repository_dispatch,omitempty"`
}

RollbackConfig is the opt-in configuration block for the generated rollback workflow (#181). It is absent by default: when nil, the rollback workflow is byte-identical to the workflow_dispatch-only baseline.

RepositoryDispatch, when set, adds a repository_dispatch trigger so an external system (an alerting or incident pipeline) can fire the same N-1 rollback the manual path performs by calling the GitHub dispatches API. The dispatch carries the rollback parameters in client_payload, and the preflight job coalesces the reads so both the manual (github.event.inputs.*) and external (github.event.client_payload.*) trigger paths resolve the same target.

type RolloutConfig added in v0.2.0 

type RolloutConfig struct {
	// Type is one of default|rolling|canary|blue_green (default: default).
	Type string `yaml:"type,omitempty" json:"type,omitempty"`
	// MaxParallel caps concurrent rollout waves (e.g. region-by-region).
	MaxParallel int `yaml:"max_parallel,omitempty" json:"max_parallel,omitempty"`
	// FailFast is a pointer so "unset" differs from "false".
	FailFast *bool `yaml:"fail_fast,omitempty" json:"fail_fast,omitempty"`
	// Canary is the reserved canary sub-block, used when type == canary.
	Canary *CanaryConfig `yaml:"canary,omitempty" json:"canary,omitempty"`
	// BlueGreen is the reserved blue/green sub-block, used when type == blue_green.
	BlueGreen *BlueGreenConfig `yaml:"blue_green,omitempty" json:"blue_green,omitempty"`
}

RolloutConfig models deploy rollout strategy (rollout:) on a deploy callback. Deploys only. There is no shared strategy: block; matrix: and rollout: are the canonical, separate concerns.

func (*RolloutConfig) GetType added in v0.2.0 

func (r *RolloutConfig) GetType() string

GetType returns the rollout type or the default ("default").

type RunsOn added in v0.2.0 

type RunsOn struct {
	// Label holds a single scalar label (form A) such as "ubuntu-latest".
	Label string `json:"label,omitempty"`
	// Labels holds a list of labels (form B) such as [self-hosted, macOS, arm64].
	Labels []string `json:"labels,omitempty"`
	// Group holds the runner group name (form C).
	Group string `json:"group,omitempty"`
}

RunsOn models the runs_on union: a scalar label (form A), a list of labels (form B), or a {group, labels} object (form C). It mirrors the full GHA runs-on grammar so self-hosted / runner-group adoption needs no reshape.

func (RunsOn) MarshalYAML added in v0.2.0 

func (r RunsOn) MarshalYAML() (interface{}, error)

MarshalYAML emits the most compact valid form for the populated fields.

func (*RunsOn) UnmarshalYAML added in v0.2.0 

func (r *RunsOn) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML accepts a scalar label, a sequence of labels, or a {group, labels} mapping.

type ScheduleEntry added in v0.2.0 

type ScheduleEntry struct {
	Cron string `yaml:"cron" json:"cron"`
}

ScheduleEntry is a single cron schedule.

type SecretsConfig added in v0.2.0 

type SecretsConfig struct {
	// Inherit is true when the manifest opted in to inheriting all caller secrets,
	// via the scalar "inherit" or the mapping {inherit: true}.
	Inherit bool `json:"inherit,omitempty"`
	// Map holds the explicit mapping (called name -> caller name) when a mapping of
	// secret names was provided. Nil when Inherit is true.
	Map map[string]string `json:"map,omitempty"`
}

SecretsConfig models the per-callback secrets passing union. It is either the opt-in "inherit" form (the scalar "inherit", or the mapping {inherit: true}) or an explicit map of called-workflow secret name to caller secret name (the least-privilege form). An unset secrets field (nil SecretsConfig) emits no secrets block at all.

func (SecretsConfig) MarshalYAML added in v0.2.0 

func (s SecretsConfig) MarshalYAML() (interface{}, error)

MarshalYAML emits the scalar "inherit" or the explicit mapping.

func (*SecretsConfig) UnmarshalYAML added in v0.2.0 

func (s *SecretsConfig) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML accepts the scalar "inherit", the mapping {inherit: <bool>}, or a mapping of secret names. inherit may not be mixed with explicit secret keys.

type TelemetryConfig added in v0.2.0 

type TelemetryConfig struct {
	Enabled bool   `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	Adapter string `yaml:"adapter,omitempty" json:"adapter,omitempty"` // none | datadog | <future>
	// Webhook is the reserved generic vendor-neutral JSON-POST sink. RESERVED -
	// not yet wired to generation/emit. Carries the destination shape behind the
	// adapter seam so no vendor client is baked into core.
	Webhook *TelemetryWebhook `yaml:"webhook,omitempty" json:"webhook,omitempty"`
	// JobSummary toggles the run-UI summary table. A pointer so unset differs
	// from an explicit false (mirroring the FailFast "unset != false" precedent).
	// RESERVED - not yet wired to generation/emit; default-on behavior lands in a
	// later minor.
	JobSummary *bool `yaml:"job_summary,omitempty" json:"job_summary,omitempty"`
}

TelemetryConfig is the reserved vendor-neutral metrics seam.

type TelemetryWebhook added in v0.3.0 

type TelemetryWebhook struct {
	// URL is the destination the run posts telemetry to.
	URL string `yaml:"url,omitempty" json:"url,omitempty"`
	// SecretName is the name of a GitHub Actions secret holding the auth token.
	// This is a secret REFERENCE, never an inline token value: the resolver
	// reads the named secret at run time rather than carrying a raw credential
	// in the manifest. RESERVED - not yet wired to generation/emit.
	SecretName string `yaml:"secret_name,omitempty" json:"secret_name,omitempty"`
}

TelemetryWebhook is the reserved generic JSON-POST telemetry sink. RESERVED - not yet wired to generation/emit.

type TrunkConfig 

type TrunkConfig struct {
	SchemaVersion int      `yaml:"schema_version,omitempty" json:"schema_version,omitempty"` // Manifest schema generation (default: CurrentSchemaVersion when omitted)
	TrunkBranch   string   `yaml:"trunk_branch" json:"trunk_branch"`
	Triggers      []string `yaml:"triggers,omitempty" json:"triggers,omitempty"`           // Global triggers for orchestration workflow paths filter
	Environments  []string `yaml:"environments,omitempty" json:"environments,omitempty"`   // Empty = no-environment setup (library/CLI projects)
	CLIVersion    string   `yaml:"cli_version,omitempty" json:"cli_version,omitempty"`     // cascade CLI version (e.g., v1.0.0)
	TagPrefix     string   `yaml:"tag_prefix,omitempty" json:"tag_prefix,omitempty"`       // Version tag prefix (default: "v")
	ReleaseToken  string   `yaml:"release_token,omitempty" json:"release_token,omitempty"` // GitHub secret name for release operations (default: "GITHUB_TOKEN")
	StateToken    string   `yaml:"state_token,omitempty" json:"state_token,omitempty"`     // Token expression for writing manifest state to the trunk branch (default: "GITHUB_TOKEN")
	// ReleaseTokenApp optionally backs the release-token seam with a GitHub App
	// identity instead of a static secret. When set, the generator mints a
	// short-lived installation token at run time and the release steps consume it.
	ReleaseTokenApp *AppTokenSource `yaml:"release_token_app,omitempty" json:"release_token_app,omitempty"`
	// StateTokenApp optionally backs the state-token seam with a GitHub App
	// identity instead of a static secret. When set, the generator mints a
	// short-lived installation token at run time and the state-write steps consume it.
	StateTokenApp *AppTokenSource      `yaml:"state_token_app,omitempty" json:"state_token_app,omitempty"`
	ManifestFile  string               `yaml:"manifest_file,omitempty" json:"manifest_file,omitempty"` // Config file path (default: ".github/manifest.yaml")
	ManifestKey   string               `yaml:"manifest_key,omitempty" json:"manifest_key,omitempty"`   // Nested key in manifest file (default: "ci")
	ActionFolder  string               `yaml:"action_folder,omitempty" json:"action_folder,omitempty"` // Folder name for manage-release action (default: "manage-release")
	Git           *GitConfig           `yaml:"git,omitempty" json:"git,omitempty"`
	Validate      *ValidateConfig      `yaml:"validate,omitempty" json:"validate,omitempty"`
	Builds        []BuildConfig        `yaml:"builds,omitempty" json:"builds,omitempty"`     // Empty = no orchestrated builds
	Deploys       []DeployConfig       `yaml:"deploys,omitempty" json:"deploys,omitempty"`   // Empty = no deploys (library/CLI projects)
	Publish       *PublishConfig       `yaml:"publish,omitempty" json:"publish,omitempty"`   // Optional: retag artifacts after a release is published
	External      []ExternalRepoConfig `yaml:"external,omitempty" json:"external,omitempty"` // External repos this primary coordinates
	Notify        *NotifyConfig        `yaml:"notify,omitempty" json:"notify,omitempty"`     // Satellite: notify primary after dev deploy
	Release       *ReleaseConfig       `yaml:"release,omitempty" json:"release,omitempty"`
	Changelog     *ChangelogConfig     `yaml:"changelog,omitempty" json:"changelog,omitempty"`
	Concurrency   *ConcurrencyConfig   `yaml:"concurrency,omitempty" json:"concurrency,omitempty"` // Optional: top-level concurrency: block on the orchestrate workflow

	// v1 reserved-shape config-level fields (parse + structural validation only).
	RunsOn            *RunsOn                  `yaml:"runs_on,omitempty" json:"runs_on,omitempty"`                         // Default runner for cascade-owned jobs
	JobTimeoutMinutes int                      `yaml:"job_timeout_minutes,omitempty" json:"job_timeout_minutes,omitempty"` // Default timeout-minutes for cascade-owned jobs
	DispatchInputs    map[string]DispatchInput `yaml:"dispatch_inputs,omitempty" json:"dispatch_inputs,omitempty"`         // Operator-facing manual-run inputs
	ExtraTriggers     *ExtraTriggers           `yaml:"extra_triggers,omitempty" json:"extra_triggers,omitempty"`           // Non-push trigger types
	PRPreview         *PRPreviewConfig         `yaml:"pr_preview,omitempty" json:"pr_preview,omitempty"`
	ValidateCheck     *ValidateCheckConfig     `yaml:"validate_check,omitempty" json:"validate_check,omitempty"`
	MergeQueue        *MergeQueueConfig        `yaml:"merge_queue,omitempty" json:"merge_queue,omitempty"`
	DriftCheck        *DriftCheckConfig        `yaml:"drift_check,omitempty" json:"drift_check,omitempty"` // Opt-in workflow drift-check PR lane (#229)
	// Rollback configures the opt-in rollback workflow. Absent by default; when
	// set with repository_dispatch, an external signal can fire the rollback (#181).
	Rollback *RollbackConfig `yaml:"rollback,omitempty" json:"rollback,omitempty"`
	// Deployments configures opt-in GitHub Deployments API integration.
	Deployments       *DeploymentsConfig           `yaml:"deployments,omitempty" json:"deployments,omitempty"`
	PinMode           string                       `yaml:"pin_mode,omitempty" json:"pin_mode,omitempty"` // tag | sha (default tag)
	ActionPins        map[string]string            `yaml:"action_pins,omitempty" json:"action_pins,omitempty"`
	Telemetry         *TelemetryConfig             `yaml:"telemetry,omitempty" json:"telemetry,omitempty"`
	EnvironmentConfig map[string]EnvironmentConfig `yaml:"environment_config,omitempty" json:"environment_config,omitempty"`
	// Components reserves the shape for independently versioned components sharing
	// one manifest (#176). v1 contract: parse + structural validation only; no
	// generator, state, or runtime behavior is attached. Absent by default.
	Components map[string]ComponentConfig `yaml:"components,omitempty" json:"components,omitempty"`
}

TrunkConfig represents the pipeline configuration (within config: section)

func Parse 

func Parse(path string) (*TrunkConfig, error)

Parse reads and parses a manifest file with config under the default "ci" key.

func ParseWithKey 

func ParseWithKey(path, key string) (*TrunkConfig, error)

ParseWithKey reads and parses a manifest file with config under a specific key. The manifest must have the specified key (default: "ci") at the top level.

func (*TrunkConfig) ChangelogEnabled 

func (c *TrunkConfig) ChangelogEnabled() bool

ChangelogEnabled returns true if changelog generation is enabled (default: true)

func (*TrunkConfig) GetActionFolder 

func (c *TrunkConfig) GetActionFolder() string

GetActionFolder returns the configured action folder name or "manage-release" if not specified

func (*TrunkConfig) GetAllDirectPromotionOptions 

func (c *TrunkConfig) GetAllDirectPromotionOptions() []PromotionOption

GetAllDirectPromotionOptions returns all direct promotion options. Release states are determined by position, not by fake "release" environment:

  • Promotion to second-from-top env (e.g., uat) = prerelease state
  • Promotion to top env (e.g., prod) = released state

For 4 envs [dev, test, uat, prod], generates:

  • dev-to-test, dev-to-uat, test-to-uat (env-to-env, uat promotions trigger prerelease)
  • dev-to-prod, test-to-prod, uat-to-prod (includes prod deployment, triggers released)

func (*TrunkConfig) GetAllExternalDeployNames 

func (c *TrunkConfig) GetAllExternalDeployNames() []string

GetAllExternalDeployNames returns the names of all external deploys

func (*TrunkConfig) GetAllExternalDeploys 

func (c *TrunkConfig) GetAllExternalDeploys() []struct {
	Repo   *ExternalRepoConfig
	Deploy *ExternalDeployConfig
}

GetAllExternalDeploys returns all external deploys across all external repos

func (*TrunkConfig) GetAllReleaseArtifacts 

func (c *TrunkConfig) GetAllReleaseArtifacts() []struct {
	BuildName string
	Artifact  ArtifactConfig
}

GetAllReleaseArtifacts returns all artifact configs across all builds Each artifact name is prefixed with the build name for uniqueness

func (*TrunkConfig) GetAllTriggers 

func (c *TrunkConfig) GetAllTriggers() []string

GetAllTriggers returns trigger patterns for the orchestrate workflow paths filter. Priority order:

  1. Global triggers (config.triggers) - if defined, use exclusively
  2. Component triggers - collect from validate, builds, and deploys

If no triggers are defined anywhere, returns nil (orchestrate runs on all pushes).

func (*TrunkConfig) GetCLIVersion 

func (c *TrunkConfig) GetCLIVersion() string

GetCLIVersion returns the configured CLI version, resolving mutable refs to the immutable pinned default for supply-chain integrity. Supported values:

  • "" or "latest" → DefaultCLIVersion (the pinned, immutable release tag)
  • "beta" → passes through; the generator maps it to "master" (bleeding edge)
  • "vX.Y.Z" → passes through as a specific version tag

func (*TrunkConfig) GetCascadeTargets 

func (c *TrunkConfig) GetCascadeTargets() []PromotionOption

GetCascadeTargets returns all valid cascade promotion targets for manual mode These are the direct promotion options (e.g., dev-to-test, dev-to-prod)

func (*TrunkConfig) GetConcurrencyCancelInProgress 

func (c *TrunkConfig) GetConcurrencyCancelInProgress() bool

GetConcurrencyCancelInProgress returns whether to cancel older in-progress runs. Defaults to true (newer push obsoletes older). Returns false only when explicitly configured.

func (*TrunkConfig) GetConcurrencyGroup 

func (c *TrunkConfig) GetConcurrencyGroup() string

GetConcurrencyGroup returns the configured group expression or the default.

func (*TrunkConfig) GetEnvironmentIndex 

func (c *TrunkConfig) GetEnvironmentIndex(env string) int

GetEnvironmentIndex returns the index of the environment, -1 if not found

func (*TrunkConfig) GetEnvironmentsInRange 

func (c *TrunkConfig) GetEnvironmentsInRange(start, end string) []string

GetEnvironmentsInRange returns all environments from start to end (inclusive) Returns nil if start or end not found, or if end comes before start

func (*TrunkConfig) GetExternalDeploy 

func (c *TrunkConfig) GetExternalDeploy(name string) (*ExternalDeployConfig, *ExternalRepoConfig)

GetExternalDeploy returns an external deploy config by name, or nil if not found

func (*TrunkConfig) GetGitMode 

func (c *TrunkConfig) GetGitMode() string

GetGitMode returns the effective git mode (default if not specified)

func (*TrunkConfig) GetGitUserEmail 

func (c *TrunkConfig) GetGitUserEmail() string

GetGitUserEmail returns the git user.email to use

func (*TrunkConfig) GetGitUserName 

func (c *TrunkConfig) GetGitUserName() string

GetGitUserName returns the git user.name to use

func (*TrunkConfig) GetManifestFile 

func (c *TrunkConfig) GetManifestFile() string

GetManifestFile returns the configured manifest file path or ".github/manifest.yaml" if not specified

func (*TrunkConfig) GetManifestKey 

func (c *TrunkConfig) GetManifestKey() string

GetManifestKey returns the configured manifest key or "ci" if not specified

func (*TrunkConfig) GetNextEnvironment 

func (c *TrunkConfig) GetNextEnvironment(env string) string

GetNextEnvironment returns the next environment in the list, empty if last

func (*TrunkConfig) GetPinMode added in v0.2.0 

func (c *TrunkConfig) GetPinMode() string

GetPinMode returns the configured pin mode or the default ("tag").

func (*TrunkConfig) GetPromotionModes 

func (c *TrunkConfig) GetPromotionModes() []PromotionMode

GetPromotionModes returns the available promotion modes

func (*TrunkConfig) GetReleaseToken 

func (c *TrunkConfig) GetReleaseToken() string

GetReleaseToken returns the configured release token as a resolvable GitHub Actions expression. A bare secret name (e.g. "MY_TOKEN") is normalized to "${{ secrets.MY_TOKEN }}".

When release_token is unset, the result depends on state_token. The release token creates the rc tag, and creating a tag that must trigger downstream workflows (Release, the fleet, promotion) requires a trigger-capable token: GitHub deliberately suppresses workflow triggers for ref creations made with the default GITHUB_TOKEN. So when an adopter has supplied a trigger-capable state_token (typically a PAT or App-backed token for protected-trunk writes) but left release_token unset, defaulting the release token to GITHUB_TOKEN would silently break the rc-to-release chain: the rc tag fires nothing.

To avoid that silent dead-chain, an unset release_token falls back to the state token expression whenever state_token is set, reusing the trigger- capable token the adopter already configured. When both are unset, the historical "${{ secrets.GITHUB_TOKEN }}" default is preserved for back-compatibility (a single-token, same-repo setup does not need the chain). When release_token is set, it always wins.

Note on App-backed state tokens: a minted App token lives in a generator step output, not in config, so this config-layer resolver can only fall back to the static state_token string. An adopter whose state token is supplied solely via state_token_app (no static state_token) keeps the GITHUB_TOKEN default here; to arm the rc-to-release chain in that shape, set a static, trigger-capable release_token explicitly.

func (*TrunkConfig) GetReleaseTokenAppID added in v0.3.0 

func (c *TrunkConfig) GetReleaseTokenAppID() string

GetReleaseTokenAppID returns the release App's app_id as a resolvable GitHub Actions expression (a bare name becomes "${{ secrets.NAME }}"), or "" when no release App identity is configured.

func (*TrunkConfig) GetReleaseTokenAppPrivateKey added in v0.3.0 

func (c *TrunkConfig) GetReleaseTokenAppPrivateKey() string

GetReleaseTokenAppPrivateKey returns the release App's private_key as a resolvable GitHub Actions expression, or "" when no release App identity is configured. The value is a secret reference, never raw key material.

func (*TrunkConfig) GetSchemaVersion added in v0.2.0 

func (c *TrunkConfig) GetSchemaVersion() int

GetSchemaVersion returns the effective schema version: the configured value, or CurrentSchemaVersion when omitted (schema_version == 0). An omitted version is treated as the current generation for all downstream logic; ValidateSchemaVersion surfaces the accompanying "no schema_version" warning.

func (*TrunkConfig) GetStateToken added in v0.2.0 

func (c *TrunkConfig) GetStateToken() string

GetStateToken returns the configured state-write token expression or "${{ secrets.GITHUB_TOKEN }}" if not specified. This token is used to write the manifest state back to the trunk branch. On real GitHub the write goes through the REST API, so a token with permission to bypass branch protection (for example a GitHub App or bot token) can be supplied here to update a protected trunk and produce a verified, signed commit. Users should provide the full GitHub Actions expression, e.g. "${{ secrets.MY_TOKEN }}".

func (*TrunkConfig) GetStateTokenAppID added in v0.3.0 

func (c *TrunkConfig) GetStateTokenAppID() string

GetStateTokenAppID returns the state App's app_id as a resolvable GitHub Actions expression, or "" when no state App identity is configured.

func (*TrunkConfig) GetStateTokenAppPrivateKey added in v0.3.0 

func (c *TrunkConfig) GetStateTokenAppPrivateKey() string

GetStateTokenAppPrivateKey returns the state App's private_key as a resolvable GitHub Actions expression, or "" when no state App identity is configured. The value is a secret reference, never raw key material.

func (*TrunkConfig) GetTagPrefix 

func (c *TrunkConfig) GetTagPrefix() string

GetTagPrefix returns the configured tag prefix or "v" if not specified

func (*TrunkConfig) GetTriggersForDeploy 

func (c *TrunkConfig) GetTriggersForDeploy(deployName string) []string

GetTriggersForDeploy returns the trigger patterns for a deploy. If deploy has depends_on, returns the first referenced build's triggers. If deploy has own triggers, returns those. Otherwise returns nil (deploy always runs).

func (*TrunkConfig) HasCustomChangelog 

func (c *TrunkConfig) HasCustomChangelog() bool

HasCustomChangelog returns true if a custom changelog workflow is configured

func (*TrunkConfig) HasExternalRelease 

func (c *TrunkConfig) HasExternalRelease() bool

HasExternalRelease returns true if an external tool creates releases

func (*TrunkConfig) HasGPGSigning 

func (c *TrunkConfig) HasGPGSigning() bool

HasGPGSigning returns true if GPG signing is configured

func (*TrunkConfig) HasReleaseArtifacts 

func (c *TrunkConfig) HasReleaseArtifacts() bool

HasReleaseArtifacts returns true if any build has artifacts configured

func (*TrunkConfig) HasReleaseTokenApp added in v0.3.0 

func (c *TrunkConfig) HasReleaseTokenApp() bool

HasReleaseTokenApp reports whether a GitHub App identity backs the release-token seam.

func (*TrunkConfig) HasStateTokenApp added in v0.3.0 

func (c *TrunkConfig) HasStateTokenApp() bool

HasStateTokenApp reports whether a GitHub App identity backs the state-token seam.

func (*TrunkConfig) IsFirstEnvironment 

func (c *TrunkConfig) IsFirstEnvironment(env string) bool

IsFirstEnvironment returns true if env is the first (build target)

func (*TrunkConfig) IsLastEnvironment 

func (c *TrunkConfig) IsLastEnvironment(env string) bool

IsLastEnvironment returns true if env is the last (production)

func (*TrunkConfig) IsPrimary 

func (c *TrunkConfig) IsPrimary() bool

IsPrimary returns true if this repo coordinates external repos

func (*TrunkConfig) IsSatellite 

func (c *TrunkConfig) IsSatellite() bool

IsSatellite returns true if this repo notifies a primary after dev deploys

func (*TrunkConfig) IsSingleEnvironment 

func (c *TrunkConfig) IsSingleEnvironment() bool

IsSingleEnvironment returns true if only one environment is configured Single-environment projects get a Release workflow instead of Promote

func (*TrunkConfig) ReleaseEnabled 

func (c *TrunkConfig) ReleaseEnabled() bool

ReleaseEnabled returns true if release management is enabled (default: true)

func (*TrunkConfig) ResolveDependency 

func (c *TrunkConfig) ResolveDependency(depRef string, fromType string) (string, error)

ResolveDependency resolves a dependency reference to its job ID. Supports:

  • Explicit: "build:app" -> "build-app", "deploy:infra" -> "deploy-infra"
  • Implicit: "app" -> infers type based on context (deploys look in builds first)

Returns the resolved job ID and an error if ambiguous or not found.

func (*TrunkConfig) ValidateSchemaVersion added in v0.2.0 

func (c *TrunkConfig) ValidateSchemaVersion() (warnings []string, fatalErr error)

ValidateSchemaVersion checks the manifest's schema_version against the CLI's supported range and returns (warnings, fatalErr). It enforces the compatibility contract documented in docs/versioning.md:

  • omitted (0) → accept, warn (assume current)
  • MinSchemaVersion..Current-1 → accept, warn (older but supported)
  • == CurrentSchemaVersion → accept silently
  • < MinSchemaVersion (and != 0) → reject (too old; migrate)
  • > CurrentSchemaVersion → reject (newer; upgrade CLI)
  • negative → reject (invalid)

A non-nil fatalErr means the manifest must not be used for generation.

type ValidateCheckConfig added in v0.2.0 

type ValidateCheckConfig struct {
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
}

ValidateCheckConfig is the opt-in manifest-validation-as-a-PR-check lane (#41).

type ValidateConfig 

type ValidateConfig struct {
	Workflow       string                            `yaml:"workflow,omitempty" json:"workflow,omitempty"`
	Run            string                            `yaml:"run,omitempty" json:"run,omitempty"`           // rejected: inline run is no longer supported; use workflow:
	Shell          string                            `yaml:"shell,omitempty" json:"shell,omitempty"`       // rejected: inline shell is no longer supported; use workflow:
	Triggers       []string                          `yaml:"triggers,omitempty" json:"triggers,omitempty"` // File patterns that should trigger validation
	SupportsDryRun bool                              `yaml:"supports_dry_run,omitempty" json:"supports_dry_run,omitempty"`
	Inputs         map[string]interface{}            `yaml:"inputs,omitempty" json:"inputs,omitempty"`
	EnvInputs      map[string]map[string]interface{} `yaml:"env_inputs,omitempty" json:"env_inputs,omitempty"`
	RunPolicy      string                            `yaml:"run_policy,omitempty" json:"run_policy,omitempty"`
	OnFailure      string                            `yaml:"on_failure,omitempty" json:"on_failure,omitempty"`
	Retries        int                               `yaml:"retries,omitempty" json:"retries,omitempty"`
	TimeoutMinutes int                               `yaml:"timeout_minutes,omitempty" json:"timeout_minutes,omitempty"` // Job-level timeout-minutes (omits when 0)

	// v1 reserved-shape per-callback fields (parse + structural validation only).
	// The validate gate is a singleton, so the spec scopes optional_depends_on
	// (§2.11) and auto_commits (§5.5) to builds/deploys only; not here.
	Secrets     *SecretsConfig     `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	Permissions map[string]string  `yaml:"permissions,omitempty" json:"permissions,omitempty"`
	RunsOn      *RunsOn            `yaml:"runs_on,omitempty" json:"runs_on,omitempty"`
	Concurrency *ConcurrencyConfig `yaml:"concurrency,omitempty" json:"concurrency,omitempty"`
}

ValidateConfig defines a validation workflow

type VersionOverridesConfig added in v0.3.0 

type VersionOverridesConfig struct {
	// Dir is the directory holding override files. Relative, no ".." segments.
	// Empty => the implementation default (reserved).
	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`
}

VersionOverridesConfig is the reserved pointer to the override-file location. Only the addressing shape is frozen in v1; file format and the fold-into-version-calculation behavior land post-1.0 additively. Any future override values map onto the canonical version primitives in internal/version (BumpType: BumpNone/BumpPatch/BumpMinor/BumpMajor and the PreRelease line); this reservation introduces no parallel enum.

type WorkflowRunTrigger added in v0.2.0 

type WorkflowRunTrigger struct {
	Workflows []string `yaml:"workflows,omitempty" json:"workflows,omitempty"`
	Types     []string `yaml:"types,omitempty" json:"types,omitempty"`
}

WorkflowRunTrigger configures the workflow_run trigger.

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.