Repository navigation
Deployment and Releases
This page is for maintainers. It covers how changes move from a pull request to develop, staging and main, which CI checks each one, and how the demoflow npm package is published.
| Branch / event | What runs |
|---|---|
Pull request into develop
|
The Woodpecker pipeline (Biome check, build, affected tests). The GitHub Actions execution-plane and package-smoke workflows run when execution-plane paths change |
Merge into develop
|
The Woodpecker pipeline, then a staging deploy to https://demoflow-app.luna-realm.com. The GitHub workflows also run on their paths |
Merge develop → main
|
The Woodpecker pipeline with the full suite, and the release workflow that publishes to npm |
Tag vX.Y.Z
|
The release workflow, which checks the tag against the version |
main holds releases. All work lands in develop through pull requests (ADR-0002). The full procedure is in deploy/README.md.
flowchart LR
PR["Pull request"] --> WP["Woodpecker: check, build, test"]
PR --> GH["GitHub Actions: execution-plane, package-smoke (3 OSes)"]
WP --> D["develop"]
GH --> D
D --> ST["Staging: demoflow-app.luna-realm.com"]
D -- "release PR" --> M["main"]
M --> REL["release.yml: check, build, smoke, npm publish"]
REL --> T["tag vX.Y.Z"]
-
Woodpecker pipeline (.woodpecker/pipeline.yml) has these steps:
ci-image,install,check,build,test,build-staging,deploy-staging.-
check(bun run check) always runs. -
buildis skipped on pull requests that touch onlydocs/**,*.mdor.github/**. -
testdepends on the event:- On a pull request it covers the packages changed since the merge base, plus their dependents. A change to a root file (
package.json,bun.lock,turbo.json,tsconfig.json,biome.json,.woodpecker/,deploy/ci-image/) runs the full suite instead. - A push to
mainand a manual run get the full suite. - A push to
developruns no tests, because the pull request already ran them.
- On a pull request it covers the packages changed since the merge base, plus their dependents. A change to a root file (
-
-
Execution plane on three OSes (execution-plane.yml).
- Runs on
ubuntu-latest,macos-latestandwindows-latest, with Node 24 and Bun 1.4.0. - Builds the CLI and the fixture, then runs the tests of
@demoflow/core,@demoflow/engine,@demoflow/rendereranddemoflow. - Then runs the fixture's
customers,loginandfailingscenarios. Their exit codes must be 0, 0 and 1. - Uploads the videos as
demos-<os>artifacts, kept for 14 days.
- Runs on
-
Package smoke on three OSes (package-smoke.yml).
- Builds the publishable package and runs the headed
recordtests. On Linux they run underxvfb-run. - Then switches to Node 20, the package's
enginesfloor, and runsapps/cli/scripts/smoke.mjs --browsers. That packs the package, installs it into an empty directory, and runs--version,validate, an MCPtools/list, arunfrom an empty browser cache, andsetup. - On Linux it also runs the release scripts' tests (
bun run test:release).
- Builds the publishable package and runs the headed
-
Staging. After a push to
developpassescheckandbuild, two steps run:-
build-stagingbuildsdemoflow-api:staginganddemoflow-web:stagingon the agent host. -
deploy-stagingreplaces the containers.
Traffic goes Cloudflare tunnel → Caddy → api (
/api/*) or web. Staging runs the API and web scaffolding only; the CLI is not deployed. -
-
Release (.woodpecker/release.yml) has these steps:
check-version(tag events only),install,check(bun run checkandbun run test:release),build(bun run build --filter=demoflow),smoke,publishandtag.- It publishes
apps/cli/dist/npm. That is the packageapps/cli/scripts/stage.tsstages: the workspace packages bundled by esbuild, the Inter fonts, and a generatedpackage.json.
- It publishes
- On
develop, in a pull request, bumpversionin apps/cli/package.json. Merge it. - Open the release pull request
develop→main. The Woodpecker pipeline,execution-planeandpackage-smokemust all be green. - Merge it. The push to
mainrunsrelease.yml. It publishes the version if npm does not have it yet, then pushes the tagvX.Y.Z. - The tag starts a tag pipeline. It finds the version already published and passes.
A push to main without a version bump publishes nothing and passes. The dist-tag comes from scripts/release/decide.sh:
- normally
latest -
v<major>.<minor>for amaint/*branch, or for a version below the currentlatest
Start a manual Woodpecker pipeline whose message contains [demoflow-release]. It runs every step and ends with npm publish --dry-run. Nothing is published and no tag is pushed.
bun run build --filter=demoflow
node apps/cli/scripts/smoke.mjs
# with browsers, against the fixture preview:
node .github/scripts/serve-fixture.mjs start
node apps/cli/scripts/smoke.mjs --browsers
node .github/scripts/serve-fixture.mjs stopgh run list --workflow execution-plane.yml
gh run download <run-id> -n demos-windows-latest| Secret (Woodpecker) | Events | Used by |
|---|---|---|
npm_token |
manual, push, tag |
publish: an npm automation token allowed to publish demoflow
|
github_token |
push |
tag: a token with contents: write on the repository |
- Without
npm_token, a push prints a notice and passes. - Without
github_token, the tag step is skipped. - Provenance is not attached: npm accepts it only from GitHub Actions and GitLab CI.
- Pull requests and pushes to
developnever runrelease.yml. - A published npm version cannot be reused. To withdraw a broken release, run
npm deprecate demoflow@X.Y.Z "<why>", then fix it ondevelopand release a new patch. - If the publish succeeds but the tag fails, re-run the push pipeline. The publish step finds the version and the
tagstep creates the missing tag. - If a tag does not match the version,
check-versionfails before anything is built. Delete the tag. - The Woodpecker agents are Linux only. macOS and Windows coverage comes from the GitHub workflows.
Note
The repository is public. Woodpecker requires approval for pull requests from forks, because the pipeline steps mount the host's Docker socket.
- Contributing
- Installing
- Architecture
- deploy/README.md: staging one-time setup and operating commands
- ADR: 0002 develop integration, staging and OS matrix
- Specs: 6 OS matrix, 75 npm release
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference