cascade

module

v0.16.1 Latest Latest Go to latest Published: Jul 15, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/stablekernel/cascade

Links

Open Source Insights

README ¶

cascade

Declarative trunk-based CI/CD for GitHub Actions.

Define what to build and where to deploy in one manifest.
cascade generates the GitHub Actions wiring, tracks deployment state, manages releases,
and cascades promotions through your environments.

cascade is a compiler, not a control plane. You describe your environments, builds, deploys, and release policy in one manifest. cascade compiles that manifest into GitHub Actions workflows and then gets out of the way: everything runs as native GitHub Actions, with no external service, agent, or daemon watching your repository. Your build and deploy callbacks run on whatever runners you configure, GitHub-hosted or self-hosted.

How it works

The manifest (.github/manifest.yaml) holds both the pipeline configuration and the live deployment state for every environment. You run cascade generate-workflow once to compile it into GitHub Actions workflows, and commit those alongside your code. From then on the generated workflows own their own execution: a merge to trunk builds and deploys to the first environment, and a workflow_dispatch promotes the same built artifact through the rest of the chain without rebuilding it.

Read How Cascade works for the full mental model, including the release boundary and the hotfix and rollback off-ramps.

Quickstart

go install github.com/stablekernel/cascade/cmd/cascade@latest

See Getting started for the pinned-version install and the setup-cli action, both of which most teams should use instead of a bare @latest install.

Write a manifest, write your build and deploy callbacks, then generate. Callbacks must exist first: the generator reads their workflow_call outputs to wire the rest.

# .github/manifest.yaml
ci:
  config:
    schema_version: 1
    trunk_branch: main
    cli_version: v0.16.0
    environments: [dev, staging, prod]
    builds:
      - name: app
        workflow: .github/workflows/build-app.yaml

# 1. Write .github/manifest.yaml (above)
# 2. Write your build/deploy callback workflows (they must exist first)
# 3. Generate the orchestration workflows
cascade generate-workflow --config .github/manifest.yaml
# 4. Commit everything and push to trunk to run the first pipeline

The full walkthrough, including cascade init scaffolding and the four topology shapes, lives in Getting started.

What cascade generates

A single generate-workflow run compiles the manifest into the orchestrate, promote, hotfix, and rollback workflows plus the release composite action, with opt-in companions emitted only when their manifest block is present. See Generated workflows for the full anatomy of each file.

Highlights

Compiler model. One manifest compiles into a full multi-environment pipeline of native GitHub Actions workflows.
Single or multi-component. A single-component repo is the default; declare more to version, promote, hotfix, and roll back each independently from one manifest, each in its own tag and state namespace. Monorepos are native, not bolted on. See Components.
SHA-keyed promotion ladder. Promote the exact bytes that passed the previous environment, never a per-stage rebuild. See Promote a release.
Security by construction. Every caller job carries a per-callback least-privilege permissions: block, including OIDC id-token: write. See Callback contract.
Self-healing supply chain. Third-party action pins live in one source of truth, and a reconcile companion adopts external pin bumps back into the manifest. See Action pins.
Hotfix and rollback, race-safe. Patch or revert a single environment with correct, race-safe concurrency. See Run a hotfix and Roll back an environment.

Preview a pipeline before you merge: simulate traces what a change would build and deploy, and graph renders the environment chain.

A fuller manifest puts a few fields to work: web builds only after api, and each build and deploy runs only when its triggers match the changed paths.

# .github/manifest.yaml
ci:
  config:
    schema_version: 1
    trunk_branch: main
    cli_version: v0.16.0
    environments: [dev, staging, prod]
    builds:
      - name: api
        workflow: .github/workflows/build-api.yaml
        triggers: ["api/**"]
      - name: web
        workflow: .github/workflows/build-web.yaml
        triggers: ["web/**"]
        depends_on: [api]
    deploys:
      - name: services
        workflow: .github/workflows/deploy.yaml
        triggers: ["api/**", "web/**"]

Full field-by-field detail lives in the manifest reference.

Documentation

Start here
Why Cascade	What cascade is, when to use it, and how it compares to adjacent tools.
How Cascade works	The mental model: trunk, environment chain, release boundary.
Getting started	Install, scaffold or hand-write a manifest, and run your first pipeline.

Task guides
Adopt an existing pipeline	Migrate without a rewrite; coexist with tools you already use.
Promote a release	Trigger and watch a promotion.
Run a hotfix	Patch one environment without touching the others.
Roll back an environment	Revert an environment to its previous version.

Reference
Manifest	Every manifest field, its emission status, and its default.
CLI	Every command, flag, environment variable, and exit code.
Callback contract	The inputs and outputs your build/deploy/publish workflows exchange with cascade.
Generated workflows	The exact file set and the anatomy of each generated workflow.

See the full sidebar for the rest, including security and internals.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for development setup and workflow details.

cascade uses the Developer Certificate of Origin. Sign off each commit with git commit -s. By participating you agree to the Code of Conduct.

License

Apache 2.0. See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
cascade command Command cascade compiles a declarative manifest (.github/manifest.yaml) into GitHub Actions workflows for trunk-based, multi-environment release pipelines, and provides the lifecycle subcommands the generated workflows invoke, such as orchestrate, promote, release, hotfix, and rollback.	Command cascade compiles a declarative manifest (.github/manifest.yaml) into GitHub Actions workflows for trunk-based, multi-environment release pipelines, and provides the lifecycle subcommands the generated workflows invoke, such as orchestrate, promote, release, hotfix, and rollback.
internal
branchprotection Package branchprotection emits the JSON body an operator applies to GitHub's branch-protection API for a cascade-managed trunk.	Package branchprotection emits the JSON body an operator applies to GitHub's branch-protection API for a cascade-managed trunk.
changelog Package changelog generates release changelogs from conventional commit history, parsing commits into typed entries and enriching authors with GitHub usernames for release notes.	Package changelog generates release changelogs from conventional commit history, parsing commits into typed entries and enriching authors with GitHub usernames for release notes.
changes Package changes detects which files changed between two commits and, from the path rules in the manifest, which component builds and deploys those changes trigger.	Package changes detects which files changed between two commits and, from the path rules in the manifest, which component builds and deploys those changes trigger.
config Package config defines the cascade manifest schema and its parsing, validation, and state handling.	Package config defines the cascade manifest schema and its parsing, validation, and state handling.
coverage Package coverage records, for every workflow kind the generator emits, the executing coverage that exercises it: e2e scenarios, e2e harness tests, and fleet lanes.	Package coverage records, for every workflow kind the generator emits, the executing coverage that exercises it: e2e scenarios, e2e harness tests, and fleet lanes.
environments Package environments emits a per-environment configuration file an operator applies to GitHub's Environments REST API.	Package environments emits a per-environment configuration file an operator applies to GitHub's Environments REST API.
external Package external provides CLI commands for handling external repo notifications.	Package external provides CLI commands for handling external repo notifications.
fleetreconcile Package fleetreconcile holds the run-ledger reconcile core that backs the fleet-reconcile reusable workflow.	Package fleetreconcile holds the run-ledger reconcile core that backs the fleet-reconcile reusable workflow.
fleetreconcile/cmd command Command fleet-reconcile is the runnable wrapper around the fleetreconcile core.	Command fleet-reconcile is the runnable wrapper around the fleetreconcile core.
generate Package generate is the compiler core: it renders a parsed manifest into the GitHub Actions workflow files that run the pipeline.	Package generate is the compiler core: it renders a parsed manifest into the GitHub Actions workflow files that run the pipeline.
ghaoutput Package ghaoutput writes step outputs to the file named by $GITHUB_OUTPUT, using plain key=value lines for single-line values and randomized heredoc delimiters for multiline values so untrusted content cannot forge additional outputs.	Package ghaoutput writes step outputs to the file named by $GITHUB_OUTPUT, using plain key=value lines for single-line values and randomized heredoc delimiters for multiline values so untrusted content cannot forge additional outputs.
git Package git wraps the git CLI for the repository operations cascade needs: listing changed files and commits between SHAs, reading and validating version tags, querying branches, and committing and pushing state updates with rebase and retry handling.	Package git wraps the git CLI for the repository operations cascade needs: listing changed files and commits between SHAs, reading and validating version tags, querying branches, and committing and pushing state updates with rebase and retry handling.
github Package github queries the GitHub Actions jobs API through the gh CLI and maps workflow job names to their conclusions.	Package github queries the GitHub Actions jobs API through the gh CLI and maps workflow job names to their conclusions.
globals Package globals provides access to global CLI flags and state.	Package globals provides access to global CLI flags and state.
graph Package graph drives the cascade visualizer from the command line.	Package graph drives the cascade visualizer from the command line.
hotfix Package hotfix plans and validates per-environment hotfixes that apply a trunk commit onto an environment pinned to an older trunk base.	Package hotfix plans and validates per-environment hotfixes that apply a trunk commit onto an environment pinned to an older trunk base.
initcmd Package initcmd implements the "cascade init" command, which scaffolds a new project: it renders a starter manifest and matching reusable-workflow stubs, self-checks them through the real generator, and writes them to disk so a repository can adopt cascade with a working configuration on the first try.	Package initcmd implements the "cascade init" command, which scaffolds a new project: it renders a starter manifest and matching reusable-workflow stubs, self-checks them through the real generator, and writes them to disk so a repository can adopt cascade with a working configuration on the first try.
log Package log provides structured logging with INFO, DEBUG, and TRACE levels.	Package log provides structured logging with INFO, DEBUG, and TRACE levels.
orchestrate Package orchestrate provides CLI commands for CI/CD orchestration.	Package orchestrate provides CLI commands for CI/CD orchestration.
output Package output provides helpers for outputting data to GitHub Actions and JSON.	Package output provides helpers for outputting data to GitHub Actions and JSON.
pinreconcile Package pinreconcile implements the pin-reconciliation engine: adopting an external action-pin change back into the manifest and regenerating so every owned file agrees with it again.	Package pinreconcile implements the pin-reconciliation engine: adopting an external action-pin change back into the manifest and regenerating so every owned file agrees with it again.
plan Package plan implements the read-only "cascade plan" command.	Package plan implements the read-only "cascade plan" command.
promote Package promote implements environment promotion: moving an already built artifact from one environment to the next in the chain.	Package promote implements environment promotion: moving an already built artifact from one environment to the next in the chain.
release Package release manages GitHub releases over the GitHub REST API: creating and updating the draft release that accumulates changes and publishing it when a version is released.	Package release manages GitHub releases over the GitHub REST API: creating and updating the draft release that accumulates changes and publishing it when a version is released.
reset Package reset provides functionality to reset test repositories by wiping releases, tags, and optionally resetting state in the manifest.	Package reset provides functionality to reset test repositories by wiping releases, tags, and optionally resetting state in the manifest.
rollback Package rollback implements the `cascade rollback` command: explicit re-promotion of a prior version or SHA to a target environment.	Package rollback implements the `cascade rollback` command: explicit re-promotion of a prior version or SHA to a target environment.
scaffold Package scaffold renders a starter cascade manifest and the matching reusable-workflow stubs for a project, so a new repository can adopt cascade with a working, self-consistent configuration on the first try.	Package scaffold renders a starter cascade manifest and the matching reusable-workflow stubs for a project, so a new repository can adopt cascade with a working, self-consistent configuration on the first try.
schema Package schema embeds the hand-authored JSON Schema for the cascade manifest and exposes it to the CLI and to editors.	Package schema embeds the hand-authored JSON Schema for the cascade manifest and exposes it to the CLI and to editors.
setupcli Package setupcli holds the hermetic fixture tests for the setup-cli composite action's install script (.github/actions/setup-cli/install.sh).	Package setupcli holds the hermetic fixture tests for the setup-cli composite action's install script (.github/actions/setup-cli/install.sh).
simulate Package simulate implements the what-if engine behind cascade simulate: it applies a hypothetical promote, rollback, release, or hotfix action to an in-memory copy of the manifest and reports the resulting state diff and side effects without changing anything.	Package simulate implements the what-if engine behind cascade simulate: it applies a hypothetical promote, rollback, release, or hotfix action to an in-memory copy of the manifest and reports the resulting state diff and side effects without changing anything.
statewrite Package statewrite provides the shared optimistic-lock retry used by every finalize verb (orchestrate, promote, rollback, hotfix) when it commits the manifest to the trunk branch through the GitHub Contents REST API.	Package statewrite provides the shared optimistic-lock retry used by every finalize verb (orchestrate, promote, rollback, hotfix) when it commits the manifest to the trunk branch through the GitHub Contents REST API.
status Package status implements the cascade status command group: it reads the deployed state recorded in the manifest for environments, builds, and deploys, and includes a consistency check that compares recorded state against the repository's remote branches.	Package status implements the cascade status command group: it reads the deployed state recorded in the manifest for environments, builds, and deploys, and includes a consistency check that compares recorded state against the repository's remote branches.
taggrammar Package taggrammar is the single source of truth for the shape of cascade's own release tags.	Package taggrammar is the single source of truth for the shape of cascade's own release tags.
verify Package verify implements the read-only "cascade verify" command.	Package verify implements the read-only "cascade verify" command.
version Package version provides semantic versioning utilities for release management.	Package version provides semantic versioning utilities for release management.
visualize Package visualize builds a render-agnostic view of a cascade pipeline and emits it as a diagram.	Package visualize builds a render-agnostic view of a cascade pipeline and emits it as a diagram.