https://github.com/stablekernel/cascade-example-dryrun
cascade fleet example: dry-run promote/rollback and native GitHub Deployments
https://github.com/stablekernel/cascade-example-dryrun
Last synced: 14 days ago
JSON representation
cascade fleet example: dry-run promote/rollback and native GitHub Deployments
- Host: GitHub
- URL: https://github.com/stablekernel/cascade-example-dryrun
- Owner: stablekernel
- Created: 2026-07-20T05:07:09.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2026-07-20T05:26:08.000Z (19 days ago)
- Last Synced: 2026-07-20T07:13:29.575Z (19 days ago)
- Size: 23.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# cascade-example-dryrun
A cascade fleet example that exercises two runtime-semantic properties only real
GitHub Actions can show: the native GitHub Deployments integration, and the
dry-run promote and rollback rehearsals. Both depend on real-GitHub behavior the
local act/gitea harness cannot express, which is why they need a live-fleet
example repo.
## What this repo proves
1. **Native GitHub Deployments.** With `deployments.enabled`, a real
(non-dry-run) orchestrate run deploys `staging` and its finalize job creates a
real GitHub Deployment through the Deployments API, marks it `in_progress`,
then reports a terminal `success` status carrying the environment's
`environment_url`. act and gitea have no Deployments API, so only real GitHub
can observe the Deployment record and its status.
2. **Dry-run promote is a rehearsal.** A promote dispatched with `dry_run=true`
concludes success while its `promote`, `deploy`, and finalize-mutation steps
are skipped, and the committed manifest state, the git tags and releases, and
the GitHub Deployments are all left unchanged.
3. **Dry-run rollback is a rehearsal.** A rollback dispatched with `dry_run=true`
resolves and prints its target, concludes success, and skips its `deploy` and
`finalize` jobs, leaving state, tags, and Deployments unchanged.
The "a dry run created no Deployment" assertions are real-GitHub-only checks: the
native Deployment steps are gated on a non-dry-run run, and only a repo with a
live Deployments API can prove a dry run created no Deployment record.
## Manifest shape
Two environments, each with an `environment_url`, and one deploy:
| Field | Value |
| --- | --- |
| `environments` | `staging` (`https://staging.example.com`), `prod` (`https://app.example.com`) |
| `deployments` | `enabled: true`, `keep_prior_active: true` |
| `deploys` | `app` (callee `deploy-app.yaml`) |
| `builds` | `build` stub, so the promote chain is valid |
`state.prod` carries a single deploy-history ring entry. That entry gives the
dry-run rollback a resolvable prior target (resolved from the ring, no git
lookup), so the rollback rehearsal can run and be asserted non-mutating without
first establishing two real prod deployments on every suite run. `state.staging`
starts empty; the suite's real orchestrate run establishes it (and the positive
native-Deployment proof) at run time.
## Scenario suite
`scenario-suite.yaml` runs one real lifecycle and two dry-run rehearsals:
- merges a source change to drive a real orchestrate run, then asserts a native
`staging` Deployment was created and concluded `success`;
- dispatches `promote` with `dry_run=true` and asserts the run is green, the
mutating jobs are skipped, and state, tags, releases, and Deployments are
unchanged; and
- dispatches `cascade-rollback` with `dry_run=true` and asserts the run is
green, the mutating jobs are skipped, and state, tags, and Deployments are
unchanged.
Every run the suite causes is recorded in the fleet ledger, and the final
reconcile job fails closed on any unregistered run.
## Layout
```
.github/manifest.yaml cascade manifest (config plus live state)
.github/workflows/build.yaml build callee stub
.github/workflows/deploy-app.yaml deploy callee
.github/workflows/orchestrate.yaml generated CI on trunk merges
.github/workflows/promote.yaml generated environment promotion
.github/workflows/cascade-rollback.yaml generated rollback
.github/workflows/cascade-hotfix.yaml generated hotfix
.github/workflows/scenario-suite.yaml driver and assertions
```
The orchestrate, promote, hotfix, and rollback workflows and the
`manage-release` action are generated by cascade from the manifest. Run
`cascade generate-workflow` after editing the manifest.