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.