Skip to content
Kodakodadocs
Governance

Release process

How Koda cuts releases and what's promised.

Koda ships through the npm-published @openkodaai/koda CLI and matching GitHub Releases. Every release is cut from main by version, gated on CI, and recoverable if publication half-fails. This page explains what that looks like day-to-day.

Versioning

Koda follows semantic versioning with a light touch. The version number signals intent, not a contract you can litigate.

  • Patch (1.0.X) — bug fixes, documentation updates, internal refactors with no user-visible behaviour change.
  • Minor (1.X.0) — new features, new surfaces, backward-compatible additions to API shape or configuration.
  • Major (X.0.0) — breaking changes to the configured surface (API routes, env var names, on-disk state layout).
What's stable

The control-plane OpenAPI contract at /openapi/control-plane.json, the runtime API surface, env var names, and the on-disk schema for durable state are stability commitments. Internal Python modules, skill file layout details, and dashboard component internals may move without notice.

Cadence

Releases ship on demand rather than on a fixed calendar. A patch release can land any time there's a fix worth shipping; minors accumulate until there's a meaningful feature set or the team decides it's time. There is no "freeze week" — stability lives in CI, not in a schedule.

How a release is cut

Release machinery is driven by version changes landing on main. The pipeline has four gates:

  1. Version bump on main. The repository version changes (in packages/cli/package.json and pyproject.toml) via a PR that merges to main.
  2. CI passes. Both the pr-quality and security workflows must pass on the merge commit. Either failing blocks the release.
  3. Tag creation. GitHub Actions creates the matching v<version> tag on the validated commit.
  4. Publish workflow. The tag triggers release publication: npm package, GHCR images, GitHub Release assets. All three come from the same tag.

Recovery from partial publications

Publishing occasionally misfires — a transient npm registry error, a GHCR hiccup, a missing checksum. Two behaviours keep the release honest:

  • Tag-cut workflow redispatch. If the tag already exists on the validated commit but the GitHub release is still draft, assets are missing, or the npm dist-tag is wrong, the tag-cut workflow triggers the publish workflow again for recovery. It doesn't silently drop the failure.
  • Fail-loud on escaped tags. If the tag already belongs to an older commit and publication is incomplete, the workflow fails loudly so the next merge must ship a new patch version instead of trying to reuse an escaped semantic tag.

What ships

The scoped npm package @openkodaai/koda ships the product channel — the same release bundle attached to the GitHub release:

  • The CLI binary itself.
  • The pinned release manifest (release.yaml) — versions of Docker images, checksums, migration requirements.
  • The compose / bootstrap bundle.
  • Release checksums and SBOM metadata.
npm installs the product, not the source

npm install -g @openkodaai/koda installs the product channel. It's the supported distribution — not a developer's convenience, and not the source tree. The source is what you clone; the product is what you install.

User update path

Users upgrade through the CLI. The update command pulls the latest release, restarts the stack, runs the doctor, and rolls back automatically if post-update health is red.

bash
koda update

Major version bumps may also require manual migration steps. When they do, the release notes call them out explicitly and the update command surfaces them before proceeding.

Release notes

Every release on GitHub ships with notes summarising user-visible changes, migration steps (if any), and known issues. Patch releases typically have terse notes; minors and majors are more narrative.

Deprecations

When something is on a deprecation path, it's announced in release notes, surfaced as a warning in the dashboard and/or CLI, and kept working for at least one minor version before removal. No silent breakage.

Next steps