generate

type ActionPinEntry ¶ added in v0.9.0

type ActionPinEntry = actionPinEntry

ActionPinEntry is one action's pin record as authored in action_pins.yaml.

type CallbackInfo ¶

type CallbackInfo struct {
	Name           string // Original name from config (e.g., "app")
	JobID          string // Prefixed job ID (e.g., "build-app")
	DisplayName    string // Display name (e.g., "Build (app)")
	Type           string // "build" or "deploy" or "validate"
	Workflow       string
	RunPolicy      string
	OnFailure      string
	Retries        int
	Matrix         *config.MatrixConfig // Build fan-out; nil for deploys and validate
	SupportsDryRun bool                 // When true, dry-run promotes invoke the callback with dry_run: true instead of skipping it

	// Per-callback job attributes carried from config. GHA forbids
	// runs-on/concurrency/timeout-minutes on a reusable-workflow uses: caller
	// job, and schema validation rejects runs_on/concurrency/timeout_minutes on
	// reusable callbacks, so those fields are populated from config but never
	// emitted as job-level keys. permissions: is different: GitHub allows it on a
	// uses: caller job, so Permissions IS rendered as a job-level permissions:
	// block scoped to exactly this callback (least privilege; see
	// writeCallbackPermissions). These scopes are not merged into the workflow's
	// top-level permissions block, keeping the OIDC blast radius confined to this
	// one caller job.
	TimeoutMinutes int                       // Per-callback timeout-minutes; validated-against, never emitted (belongs inside the called workflow)
	RunsOn         *config.RunsOn            // Per-callback runner selection (#12); validated-against, never emitted
	Permissions    map[string]string         // Per-callback job permissions, incl. id-token: write OIDC (#35, #15); emitted as job-level permissions:
	Concurrency    *config.ConcurrencyConfig // Per-callback concurrency override (#17); validated-against, never emitted

	// PassthroughArtifact declares GHA artifact upload/download steps to inject
	// around this job's callback invocation, enabling inter-job artifact passing
	// within a single orchestrate run (#16).
	PassthroughArtifact *config.PassthroughArtifact

	// Secrets holds the per-callback secrets passing config. Nil means no secrets
	// block is emitted at all (the default; secrets: inherit is opt-in). When
	// non-nil and Inherit is true, secrets: inherit is emitted. When non-nil with
	// an explicit Map, a secrets: block with per-entry ${{ secrets.CALLER_NAME }}
	// expressions is emitted instead.
	Secrets *config.SecretsConfig
}

CallbackInfo holds information about a callback

type DependencyGraph ¶

type DependencyGraph struct {
	Nodes map[string]CallbackInfo // job ID -> info
	Edges map[string][]string     // job ID -> hard dependencies (as job IDs)

	// OptionalEdges holds optional_depends_on edges (job ID -> dependencies as
	// job IDs). Optional deps add to a job's needs: for ordering but do NOT
	// contribute a skip-gate to its if: condition. The job still runs when an
	// optional dep was skipped because its triggers didn't match (#18).
	OptionalEdges map[string][]string

	// Order lists every job ID in manifest declaration order (validate, then
	// builds, then deploys, each in the order they appear in config). It is the
	// deterministic seed for TopologicalSort: iterating Nodes (a map) directly
	// would randomize emitted job order, needs: lists, and if: conditions across
	// runs because Go randomizes map range order per process.
	Order []string
}

DependencyGraph represents the callback dependency graph Uses prefixed job IDs (build-app, deploy-app) to allow name reuse across sections

func BuildDependencyGraph(cfg *config.TrunkConfig) *DependencyGraph

func (g *DependencyGraph) GetAllDependencies(node string) []string

func (g *DependencyGraph) GetDirectDependencies(node string) []string

func (g *DependencyGraph) GetOptionalDependencies(node string) []string

func (g *DependencyGraph) TopologicalSort() ([]string, error)

type DriftCheckGenerator ¶ added in v0.3.0

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

DriftCheckGenerator emits the opt-in workflow drift-check lane (#229).

It mirrors cascade's own dogfood: a pull_request job builds nothing dangerous, runs cascade verify against the manifest, captures the result as an artifact, and re-exits on drift to keep the PR gate red. The pull_request job is strictly read-only (contents: read, no secrets, posts no comment) so a fork PR cannot abuse it.

When Comment is enabled it also emits a fork-safe workflow_run companion that runs in the base-repo context with a scoped write token, downloads the artifact (data only), and posts a sticky comment. The companion derives the target PR number ONLY from trusted workflow_run run metadata (the source run's pull_requests array, or a head-SHA lookup for fork PRs), never from the fork-controlled artifact, so a fork cannot redirect the comment at another PR.

func NewDriftCheckGenerator(cfg *config.TrunkConfig, baseDir string) *DriftCheckGenerator

func (g *DriftCheckGenerator) Enabled() bool

func (g *DriftCheckGenerator) Generate() (string, error)

func (g *DriftCheckGenerator) GenerateComment() (string, error)

type ExternalUpdateGenerator ¶

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

ExternalUpdateGenerator handles external-update workflow generation

func NewExternalUpdateGenerator(cfg *config.TrunkConfig, baseDir string) *ExternalUpdateGenerator

func (g *ExternalUpdateGenerator) Generate() (string, error)

type Generator ¶

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

Generator handles workflow file generation

func NewGenerator(cfg *config.TrunkConfig, baseDir string) *Generator

func (g *Generator) Generate() (string, error)

func (g *Generator) SetState(state map[string]*config.EnvState)

func (g *Generator) Validate() []string

type HotfixGenerator ¶ added in v0.2.0

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

HotfixGenerator emits the cascade-hotfix workflow. It cherry-picks a trunk fix onto a diverged intermediate environment by replaying the commit on an env/<env> integration branch, opening a resolution pull request, and then building, deploying, and finalizing the hotfix once that pull request merges.

The workflow carries two triggers in one file: a workflow_dispatch entry that plans and applies the cherry-pick, and a pull_request (closed) entry that runs the build, deploy, and finalize stages when the resolution pull request merges. The clean-path merge runs as the configured state token so the merge is trigger capable and the pull_request (closed) chain actually fires; a merge authored by the default GITHUB_TOKEN would not emit that event.

This generator is gated on the configured environment count: it emits only when two or more environments are declared, because a single-environment pipeline has no intermediate target to hotfix onto.

func NewHotfixGenerator(cfg *config.TrunkConfig, baseDir string) *HotfixGenerator

func (g *HotfixGenerator) Enabled() bool

func (g *HotfixGenerator) Generate() (string, error)

type MergeQueueGenerator ¶ added in v0.2.0

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

MergeQueueGenerator emits the opt-in merge-queue validation lane. When config.merge_queue.enabled is set, cascade generates a merge_group-triggered workflow that validates the prospective trunk commit with cascade's own logic: it runs `cascade parse-config` as a validity gate and a dry-run `cascade orchestrate setup` to preview the build/deploy decisions against the merge-group candidate ref. The lane is read-only (no state writes, no releases, no deploys) and reports a status the merge queue can require.

This generator owns the LANE behavior. The raw merge_group trigger itself is expressible separately under extra_triggers.merge_group; the two are intentionally distinct.

func NewMergeQueueGenerator(cfg *config.TrunkConfig, baseDir string) *MergeQueueGenerator

func (g *MergeQueueGenerator) Enabled() bool

func (g *MergeQueueGenerator) Generate() (string, error)

type PRPreviewGenerator ¶ added in v0.2.0

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

PRPreviewGenerator emits the opt-in read-only PR plan-preview workflow (#40).

The workflow runs on pull_request and is strictly read-only: it validates the manifest, detects which builds/deploys this merge would trigger against the PR diff, and dry-runs the applicable deploy callbacks, then writes a human-readable plan to $GITHUB_STEP_SUMMARY. When Comment is set it also posts (or updates) that plan as a PR comment via actions/github-script.

dry_run is enforced (--dry-run is always passed, never sourced from an input) so the preview can never create a release, write state, or trigger a deploy.

func NewPRPreviewGenerator(cfg *config.TrunkConfig, baseDir string) *PRPreviewGenerator

func (g *PRPreviewGenerator) Generate() (string, error)

type PinMismatch ¶ added in v0.9.0

type PinMismatch struct {
	File        string
	Line        int
	Action      string
	WantSHA     string
	WantVersion string
	GotRef      string
	GotComment  string
}

PinMismatch is one governed "uses:" line whose pinned ref or version comment disagrees with the action-pins manifest. File and Line locate it; Want* hold the manifest's canonical values; Got* hold what the file actually carries.

func ScanUsesForPinDrift(file, content string, manifest map[string]actionPinEntry) []PinMismatch

func (m PinMismatch) String() string

type PlanOptions ¶ added in v0.3.0

type PlanOptions struct {
	ConfigPath        string
	ManifestKey       string
	ActionFolder      string
	OutputPath        string
	PromoteOutputPath string
	// PinOverridesPath, when non-empty, names an on-disk action_pins.yaml whose
	// pins overlay cfg.ActionPins (via ApplyDiskPinOverrides) before any
	// generator runs. A version-pinned reconcile binary uses this to regenerate
	// against a repo's current pins instead of the binary's stale compiled-in
	// defaultActionPins copy; an explicit user action_pins override still wins.
	PinOverridesPath string
}

PlanOptions configures a Plan run. The fields mirror the generate-workflow flags that affect which files are emitted and where, so a Plan reproduces the generate command's full-set output without touching the filesystem.

type PlannedFile ¶ added in v0.3.0

type PlannedFile struct {
	Path    string
	Content string
}

PlannedFile is a single workflow or action file the manifest would generate, paired with its rendered content. Path mirrors the exact location the generate command writes to: relative paths for the workflow files (resolved against the current working directory) and an absolute path under baseDir for the composite action.

func Plan(opts PlanOptions) ([]PlannedFile, error)

func RenderLocalActions(baseDir string, cfg *config.TrunkConfig) (PlannedFile, error)

type PromoteGenerator ¶

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

PromoteGenerator handles promote workflow generation

func NewPromoteGenerator(cfg *config.TrunkConfig, baseDir string) *PromoteGenerator

func (g *PromoteGenerator) Generate() (string, error)

func (g *PromoteGenerator) SetState(state map[string]*config.EnvState)

type ReconcileGenerator ¶ added in v0.9.0

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

ReconcileGenerator emits the opt-in emitted pin-reconcile companion (#443).

A pull_request job runs strictly read-only: it computes the PR's changed workflow files, runs `cascade reconcile --check` (a pinned release binary, never a `go run` off the repository's own source), and uploads the result as a data-only artifact. It carries no secrets and no write permission, so a fork PR cannot abuse it.

A workflow_run companion (GenerateCompanion) subscribes to completions of that detector, resolves the target PR from trusted workflow_run metadata only, and, when the artifact reports relevance, fetches the PR's head files as data, runs the pinned cascade binary to adopt the bump into the manifest, and pushes (or opens a followup PR) with the trigger-capable state token.

func NewReconcileGenerator(cfg *config.TrunkConfig, baseDir string, opts ...ReconcileOption) *ReconcileGenerator

func (g *ReconcileGenerator) Enabled() bool

func (g *ReconcileGenerator) Generate() (string, error)

func (g *ReconcileGenerator) GenerateCompanion() (string, error)

type ReconcileOption ¶ added in v0.9.1

type ReconcileOption func(*ReconcileGenerator)

ReconcileOption customizes a ReconcileGenerator. Options are the additive, variadic tail of NewReconcileGenerator so new behavior never changes the two-argument signature callers already depend on.

func WithOwnRepo() ReconcileOption

type ReleaseGenerator ¶

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

ReleaseGenerator handles release workflow generation for single-environment projects

func NewReleaseGenerator(cfg *config.TrunkConfig, baseDir string) *ReleaseGenerator

func (g *ReleaseGenerator) Generate() (string, error)

type RollbackGenerator ¶ added in v0.2.0

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

RollbackGenerator emits the cascade-rollback workflow. The workflow re-deploys a prior version or SHA to an environment: a read-only preflight job resolves the target, one deploy job per configured deployable re-runs the deploy keyed on the resolved SHA, and a finalize job applies the state write back to trunk (marking the environment diverged until a forward promotion rejoins it).

The deploy stage reuses the same deploy callbacks (reusable-workflow, or matrix) the promote workflow drives; there is no separate rollback deploy path. The generator is gated on the configured environment count: it emits only when at least one environment is declared.

func NewRollbackGenerator(cfg *config.TrunkConfig, baseDir string) *RollbackGenerator

func (g *RollbackGenerator) Enabled() bool

func (g *RollbackGenerator) Generate() (string, error)

type ValidateCheckGenerator ¶ added in v0.2.0

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

ValidateCheckGenerator emits the opt-in manifest-validation PR check. When config.validate_check.enabled is set, cascade generates a lightweight pull_request workflow that runs `cascade parse-config` against the manifest and fails when the manifest is invalid, so a malformed configuration cannot merge to trunk. The check validates cascade's own configuration only: it does not run the consumer's build/test CI, requests contents: read alone, and has no dry-run or comment side effects.

func NewValidateCheckGenerator(cfg *config.TrunkConfig, baseDir string) *ValidateCheckGenerator

func (g *ValidateCheckGenerator) Enabled() bool

func (g *ValidateCheckGenerator) Generate() (string, error)

type WorkflowCallConfig ¶

type WorkflowCallConfig struct {
	Inputs  map[string]WorkflowInput  `yaml:"inputs"`
	Outputs map[string]WorkflowOutput `yaml:"outputs"`
}

WorkflowCallConfig represents the workflow_call trigger configuration

type WorkflowFile ¶

type WorkflowFile struct {
	Name string                 `yaml:"name"`
	On   map[string]interface{} `yaml:"on"`
}

WorkflowFile represents a GitHub Actions workflow file structure

type WorkflowInput ¶

type WorkflowInput struct {
	Type        string      `yaml:"type"`
	Description string      `yaml:"description"`
	Required    bool        `yaml:"required"`
	Default     interface{} `yaml:"default"`
}

WorkflowInput represents an input parameter

type WorkflowOutput ¶

type WorkflowOutput struct {
	Description string `yaml:"description"`
	Value       string `yaml:"value"`
}

WorkflowOutput represents an output value