Releases and Versioning

How a merge to main becomes a release candidate and how a maintainer publishes it as a versioned release.

Every merge to main builds a release candidate. A maintainer publishes a tested candidate as a public release. Users install final releases; main is in development.

The version rule

Versions live only in git tags. Files in git hold 0.0.0. Every build computes its version from the tags and stamps it into what it publishes, and CI never commits a version back to the repository. The source tree therefore never carries a release or candidate number, and the tag is the only record of what was released.

All repositories use the same pipeline pieces from kubemoot/release-actions: one action computes the next candidate version, one sets up the release helpers, and one shell library holds the shared logic for candidates, final releases, and release notes. A repository pins a released version of these actions by commit.

From merge to release

Release candidates. Each component in a repository has its own release workflow that runs on a push to main that changes that component’s files. The workflow:

  1. Runs the component’s CI.
  2. Computes the next version from the conventional-commit messages since the component’s last release: fix:, docs:, chore:, and refactor: bump the patch number, feat: bumps the minor, and feat!:, fix!:, or a BREAKING CHANGE footer bumps the major. See Contributing.
  3. Tags the commit with a candidate version, X.Y.Z-rc.N.
  4. Builds the candidate image and chart, stamping the candidate version at build time, and pushes them to the maintainers’ own registry. Candidates are not published publicly and are not meant for installation.

Publishing a release. When a candidate has passed its tests, a maintainer runs the Publish Release workflow. It always starts as a dry run: it plans the release, packages the artifacts, shows the release notes in the run summary, and publishes nothing. The maintainer reviews the plan, then runs it again with the dry run turned off. A release publishes the exact images that were tested, copied by digest and not rebuilt, to GHCR under their final version X.Y.Z. It packages the final Helm charts with the final image versions, pushes them to oci://ghcr.io/kubemoot/charts, signs every published image and chart (see Verify images and charts), tags the candidates’ commits with the final version, runs the quickstart against the published chart, and creates the GitHub Release. A signing failure stops the release before any tag.

Publishing is per repository:

  • kubemoot publishes the operator chart together with every image it pins, and the images crews use on their own (code-sandbox, workspace-access, scheduling-mcp, test-runner).
  • crews publishes each crew chart. A published crew chart pins final Kubemoot images only. Publish Release maps each candidate pin to its final and checks, by image digest, that the final is the same image the candidate ran. It refuses the release when the digests differ or when the Kubemoot release is not published yet.
  • kmctl publishes the command-line binaries.
  • kubemoot-docs publishes this documentation site.
  • vscode-crewforge publishes the CrewForge extension.

A merged pull request therefore ships in the next published release, not at merge time.

Release notes

The notes of a GitHub Release list only what a user can see, in four groups:

  • Breaking changes
  • New: feat: commits
  • Fixed: fix: commits
  • Faster: perf: commits

Maintenance, documentation, and refactoring commits do not appear in the notes, except that this site’s own releases also list documentation changes, under Documentation. Every release links to the full list of commits since the previous release for readers who want everything.

The release notes are on each repository’s GitHub Releases page:

RepositoryRelease notes
kubemootgithub.com/kubemoot/kubemoot/releases
kmctlgithub.com/kubemoot/kmctl/releases
vscode-crewforgegithub.com/kubemoot/vscode-crewforge/releases
crewsgithub.com/kubemoot/crews/releases
kubemoot-docsgithub.com/kubemoot/kubemoot-docs/releases

CrewForge

CrewForge goes through the same release as every other component and publishes one more artifact: the extension is released to the VS Code Marketplace and to Open VSX.

StepWhat happens
CandidateEvery merge to main tags vX.Y.Z-rc.N and packages the extension without publishing it.
ReleaseA maintainer runs Publish Release. It packages the extension again at the final version, tags the commit vX.Y.Z, and creates the GitHub Release with the package attached.
Registry publishWith the registry option selected, the same run publishes the attached package to the Marketplace and to Open VSX.
ApprovalRegistry publishing runs in the protected marketplace environment. It runs only from main and waits for a maintainer to approve, with no administrator bypass.
Sign-inNo registry token is stored. The Marketplace publish signs in with a Microsoft Entra federated credential that trusts only the marketplace environment. Open VSX uses Trusted Publishing, which trusts the Publish Release workflow of the repository.
ChangelogThe Changelog tab on both registries is generated from the GitHub Releases, so it matches the release notes.

Git tags are the version

Each component has its own tag stream, so components version independently:

RepositoryFinal tag formatExample
kubemoot, operatorv<version>vX.Y.Z
kubemoot, operator chartoperator-chart-v<version>operator-chart-vX.Y.Z
kubemoot, other components<component>-v<version>agent-runtime-vX.Y.Z
crews, each crew<crew>-v<version>homelab-pilot-crew-vX.Y.Z
kmctlv<version>vX.Y.Z
vscode-crewforge, CrewForgev<version>vX.Y.Z
kubemoot-docs, this sitedocs-v<version>docs-vX.Y.Z

Candidate tags add a suffix: vX.Y.Z-rc.N.

Where each repository stands

Every repository follows the rule: kmctl, vscode-crewforge, kubemoot-docs, crews, and kubemoot stamp the version at build and commit nothing.

  • A crew release candidate tracks Kubemoot’s newest candidate images, so a crew is tested against the Kubemoot build that is about to ship. Its final release pins final Kubemoot images and keeps exactly the images its candidate ran.
  • kubemoot builds its operator chart after any component it pins releases, with every image version taken from that component’s tags. The chart’s version follows the same commit rules as the components, counting the commits that touch the chart’s own files since its last release. Generated code (CRDs, RBAC, deepcopy) is committed by the developer; CI checks it and commits nothing.
  • This site rebuilds when the Kubemoot docs change without a commit: Kubemoot sends a dispatch event, and the site builds a new candidate that records the Kubemoot docs commit it was built with.

Where the artifacts are

Released artifacts are public. Candidates are not.

  • Container images are published to GHCR under ghcr.io/kubemoot, as ghcr.io/kubemoot/<image>:<version>. Only final versions are published: there is no latest tag and no candidate tag.
  • Helm charts are published as OCI artifacts under oci://ghcr.io/kubemoot/charts, for the operator chart and for each crew chart.
  • GitHub Releases are created per published component, with generated release notes. The kmctl release carries the command-line binaries for Linux, macOS, and Windows on amd64 and arm64, with a checksums file. The CrewForge release carries the extension package. The Kubemoot and crew releases carry their build provenance as <name>_<version>.intoto.jsonl. The Kubemoot release also carries the operator chart’s Grafana dashboards as JSON files, byte for byte the chart’s files and signed with the chart, for Grafana installs that import dashboards by hand (see Observability).
  • The CrewForge extension is published to the VS Code Marketplace and Open VSX.
  • This documentation site is deployed when the docs release is published.

Release images are amd64 only today.

Verify images and charts

Every container image and Helm chart that Publish Release publishes to GHCR is signed by digest with a keyless Sigstore signature and has an SLSA build provenance attestation. Both are stored in GHCR next to the artifact, and the GitHub Release carries a copy of the provenance as <name>_<version>.intoto.jsonl (gh attestation verify ... --bundle <file> checks against it offline). No key is stored anywhere: the signing certificate is issued to the release workflow’s GitHub Actions identity, so verifying means checking that identity.

The tools are cosign and the GitHub CLI. Replace <version> with a released version.

An image from kubemoot (the operator, agent-runtime, dashboard, and every other ghcr.io/kubemoot/<image>):

cosign verify ghcr.io/kubemoot/kubemoot-operator:<version> \
  --certificate-identity https://github.com/kubemoot/kubemoot/.github/workflows/publish-release.yaml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

gh attestation verify oci://ghcr.io/kubemoot/kubemoot-operator:<version> --repo kubemoot/kubemoot

The operator chart, at ghcr.io/kubemoot/charts/kubemoot-operator:

cosign verify ghcr.io/kubemoot/charts/kubemoot-operator:<version> \
  --certificate-identity https://github.com/kubemoot/kubemoot/.github/workflows/publish-release.yaml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

gh attestation verify oci://ghcr.io/kubemoot/charts/kubemoot-operator:<version> --repo kubemoot/kubemoot

A crew chart is signed by the crews release workflow:

cosign verify ghcr.io/kubemoot/charts/homelab-pilot-crew:<version> \
  --certificate-identity https://github.com/kubemoot/crews/.github/workflows/publish-release.yaml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

gh attestation verify oci://ghcr.io/kubemoot/charts/homelab-pilot-crew:<version> --repo kubemoot/crews

A successful cosign verify lists the checks it made and the signed claims, including the digest; gh attestation verify names the workflow that produced the provenance. Either command fails when the artifact was not signed by that workflow, or when its digest no longer matches what was signed. Both check the digest the tag points to, so to install exactly the bytes you verified, pin that digest (ghcr.io/kubemoot/<image>@sha256:...), which crane digest ghcr.io/kubemoot/<image>:<version> prints.

Upgrading

Upgrade the operator chart with helm upgrade, as in Installation. An existing install gets the coordinator log and resume on upgrade: a coordinator that restarts, rolls out, or loses its node resumes the discussions in progress. To keep the earlier behavior, set coordinator.eventLog and coordinator.resume to false. More than one coordinator replica with leases stays off until you set coordinator.lease. See the coordinator log and the KubemootConfig guide.

Breaking: discussion artifacts are now the workspace

What Kubemoot called discussion artifacts is now the discussion’s workspace: the scratch data agents share during one discussion. “Artifact” now means only generated work delivered to you, so the fitness results workbook keeps its name. Old names keep working for one release and warn, then they are removed. Make these changes in your crews and scripts:

  1. Tools. artifact_head, artifact_tail and artifact_grep are workspace_head, workspace_tail and workspace_grep. artifact_count, artifact_rows, artifact_select and artifact_jq are replaced by workspace_query (SQL). Update enabledTools and prompts.
  2. Access. Declare workspace.access on an Agent (none, read, write or readWrite), or workspace.defaultAccess on a Crew to set the default for its agents. A crew that declares nothing behaves as before.
  3. Configuration. spec.artifacts.queryEngine in KubemootConfig and the chart value artifacts.queryEngine are workspace.queryEngine. kubemootImage: artifactAccess in an MCPServer is workspaceAccess, and spec.images.artifactAccess (chart value images.artifactAccess) is workspaceAccess.
  4. Image. The artifact-access image is workspace-access. Change any crew value that names it.
  5. Crew names. In a crew chart, the MCPServer artifact-readops-mcp is workspace-mcp, the egress key artifact-readops-mcp is workspace-mcp, and the values mcpServers.artifactReadOps and mcpServers.artifactAccess are mcpServers.workspace. The old values still render for one release.
  6. Environment. Variables that start with ARTIFACT_ start with WORKSPACE_ (for example ARTIFACT_BUCKET is WORKSPACE_BUCKET).
  7. Mount. The /artifacts directory is /workspace in prompts and sandbox code. The old path works for one release because the same volume is also mounted at /artifacts.
  8. Storage. The NATS bucket kubemoot_discussion_artifacts is now kubemoot_workspace. Data in the old bucket is temporary and expires within 48 hours, so nothing needs copying. Start the upgrade with no discussion running.
  9. CLI and API. kmctl conversation artifact is kmctl conversation workspace (the old command warns), and the dashboard and gateway routes end in /workspace. JSON output from kmctl gains workspace keys, and the old artifact keys stay for one release.
  10. Clients. Update kmctl and CrewForge together with Kubemoot, because the published clients of the older API stop matching the new names.

API versions

The Kubemoot API group is kubemoot.ai/v1alpha1. Software versions and the API version are separate: a component release does not promote the API, and the API can change between releases while it is v1alpha1.