generate

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 PlanOptions ¶ added in v0.3.0

type PlanOptions struct {
	ConfigPath        string
	ManifestKey       string
	ActionFolder      string
	OutputPath        string
	PromoteOutputPath 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 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