cascade

module

v0.14.0-dryrun.55 Latest Latest Go to latest Published: Jul 10, 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.9.1
    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.9.1
    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
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
changes
config
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
ghaoutput
git
github
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
release
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.
simulate
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
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.