Skip to content

Deployment and Releases

Archi edited this page Oct 18, 2026 · 1 revision

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.

Overview

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.

How it works

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"]
Loading
  1. Woodpecker pipeline (.woodpecker/pipeline.yml) has these steps: ci-image, install, check, build, test, build-staging, deploy-staging.

    • check (bun run check) always runs.
    • build is skipped on pull requests that touch only docs/**, *.md or .github/**.
    • test depends 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 main and a manual run get the full suite.
      • A push to develop runs no tests, because the pull request already ran them.
  2. Execution plane on three OSes (execution-plane.yml).

    • Runs on ubuntu-latest, macos-latest and windows-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/renderer and demoflow.
    • Then runs the fixture's customers, login and failing scenarios. Their exit codes must be 0, 0 and 1.
    • Uploads the videos as demos-<os> artifacts, kept for 14 days.
  3. Package smoke on three OSes (package-smoke.yml).

    • Builds the publishable package and runs the headed record tests. On Linux they run under xvfb-run.
    • Then switches to Node 20, the package's engines floor, and runs apps/cli/scripts/smoke.mjs --browsers. That packs the package, installs it into an empty directory, and runs --version, validate, an MCP tools/list, a run from an empty browser cache, and setup.
    • On Linux it also runs the release scripts' tests (bun run test:release).
  4. Staging. After a push to develop passes check and build, two steps run:

    • build-staging builds demoflow-api:staging and demoflow-web:staging on the agent host.
    • deploy-staging replaces the containers.

    Traffic goes Cloudflare tunnel → Caddy → api (/api/*) or web. Staging runs the API and web scaffolding only; the CLI is not deployed.

  5. Release (.woodpecker/release.yml) has these steps: check-version (tag events only), install, check (bun run check and bun run test:release), build (bun run build --filter=demoflow), smoke, publish and tag.

    • It publishes apps/cli/dist/npm. That is the package apps/cli/scripts/stage.ts stages: the workspace packages bundled by esbuild, the Inter fonts, and a generated package.json.

Using it

Releasing a version

  1. On develop, in a pull request, bump version in apps/cli/package.json. Merge it.
  2. Open the release pull request develop → main. The Woodpecker pipeline, execution-plane and package-smoke must all be green.
  3. Merge it. The push to main runs release.yml. It publishes the version if npm does not have it yet, then pushes the tag vX.Y.Z.
  4. 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 a maint/* branch, or for a version below the current latest

Rehearsing a release

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.

Testing the package locally

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 stop

Downloading CI demo videos

gh run list --workflow execution-plane.yml
gh run download <run-id> -n demos-windows-latest

Settings

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.

Limits / what it never does

  • Pull requests and pushes to develop never run release.yml.
  • A published npm version cannot be reused. To withdraw a broken release, run npm deprecate demoflow@X.Y.Z "<why>", then fix it on develop and 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 tag step creates the missing tag.
  • If a tag does not match the version, check-version fails 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.

See also

Clone this wiki locally