Release process
The CI checks that run on OrkStage today, how changelogs and release notes are written, and the planned flow for images, packages, binaries and modules.
No tagged releases yet
OrkStage is developed on main and has not published a versioned release. This page lists the
checks that run today and the release flow being prepared.
What CI checks today
| Repository part | Checks |
|---|---|
Platform (.github/workflows/ci.yml) | pnpm install --frozen-lockfile, build, type check and tests. Migrations apply cleanly on Postgres, and the seed runs twice to prove it is idempotent. pnpm audit --audit-level high reports vulnerable dependencies but does not fail the build yet. |
CLI (cli/.github/workflows/ci.yml) | cargo fmt, clippy -D warnings and tests on Linux, macOS and Windows. The committed WASM package must match a fresh build and pass a smoke test. Release builds run for 8 targets. On tags, and only when the signing secrets are configured, Windows binaries get Authenticode signatures and macOS binaries get Developer ID signing and notarization. |
Planned release flow
- Versioning. Each repository uses semantic versions. A breaking API change gets a new
/api/v2route group. The template schema has its own version (platform/v1). - Platform. A tag builds and publishes
ghcr.io/orkstage/platform:<version>and the shared packages (@orkstage/contracts,/authorization,/templatesand/domain). The exported OpenAPI document is attached to the release. - Console. A tag publishes
ghcr.io/orkstage/console:<version>, pinned to a compatible range of the contracts package. - CLI. A tag publishes signed
orkbinaries for Linux (glibc and musl), macOS and Windows onx86_64andarm64, then@orkstage/scanon npm, then manifests for Homebrew, Scoop and winget. - Modules. Git tags
vX.Y.Zpublishghcr.io/orkstage/tofu-runner:<tag>. The platform pins the runner tag, so a module change is always an explicit upgrade. - Compatibility matrix.
orkstage-dev/COMPATIBILITY.mdlists the combination of versions that was tested together. Its CI runs the end to end suite against that combination. - Site. This site refreshes the API reference from the release's OpenAPI file and deploys to S3 and CloudFront.
Changelog and release notes
Every versioned repository (orkstage, orkstage-console, orkstage-cli and orkstage-modules) keeps a
CHANGELOG.md generated by git-cliff from cliff.toml. Pull requests are
squash merged, so each pull request title is one commit, and the titles of type feat, fix,
perf and docs become changelog lines, grouped, with a link to the pull request. ci, chore,
build, test and refactor stay out. Release candidates (v0.2.0-rc.1) fold into the release
they prepare.
To release version 0.2.0 of a repository:
Prepare the changelog
In the repository's Actions tab, run the Release workflow with the version 0.2.0. It
regenerates CHANGELOG.md on a branch release/v0.2.0, and its summary links to the pull request
form.
Review and merge
Open the pull request, add the version bump if the repository has one (Cargo.toml in the CLI,
package.json in the platform and the console), and merge it.
Tag
Tag the merge commit and push the tag:
git tag v0.2.0 && git push origin v0.2.0The tag creates the GitHub release with the notes of that version, written from the same
cliff.toml (in the CLI, the build creates it with the signed binaries).
Update this site
Run pnpm changelog:refresh in orkstage-site and merge the result: the
What's new page shows the latest sections of every changelog.
Security fixes ship as patch versions. The plan is for Enterprise customers to receive security advisories before public disclosure.