Releases and Versioning
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:
- Runs the component’s CI.
- Computes the next version from the conventional-commit messages since the
component’s last release:
fix:,docs:,chore:, andrefactor:bump the patch number,feat:bumps the minor, andfeat!:,fix!:, or aBREAKING CHANGEfooter bumps the major. See Contributing. - Tags the commit with a candidate version,
X.Y.Z-rc.N. - 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:
kubemootpublishes 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).crewspublishes 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.kmctlpublishes the command-line binaries.kubemoot-docspublishes this documentation site.vscode-crewforgepublishes 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:
| Repository | Release notes |
|---|---|
kubemoot | github.com/kubemoot/kubemoot/releases |
kmctl | github.com/kubemoot/kmctl/releases |
vscode-crewforge | github.com/kubemoot/vscode-crewforge/releases |
crews | github.com/kubemoot/crews/releases |
kubemoot-docs | github.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.
| Step | What happens |
|---|---|
| Candidate | Every merge to main tags vX.Y.Z-rc.N and packages the extension without publishing it. |
| Release | A 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 publish | With the registry option selected, the same run publishes the attached package to the Marketplace and to Open VSX. |
| Approval | Registry publishing runs in the protected marketplace environment. It runs only from main and waits for a maintainer to approve, with no administrator bypass. |
| Sign-in | No 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. |
| Changelog | The 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:
| Repository | Final tag format | Example |
|---|---|---|
kubemoot, operator | v<version> | vX.Y.Z |
kubemoot, operator chart | operator-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 |
kmctl | v<version> | vX.Y.Z |
vscode-crewforge, CrewForge | v<version> | vX.Y.Z |
kubemoot-docs, this site | docs-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.
kubemootbuilds 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, asghcr.io/kubemoot/<image>:<version>. Only final versions are published: there is nolatesttag 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
kmctlrelease carries the command-line binaries for Linux, macOS, and Windows onamd64andarm64, 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:
- Tools.
artifact_head,artifact_tailandartifact_grepareworkspace_head,workspace_tailandworkspace_grep.artifact_count,artifact_rows,artifact_selectandartifact_jqare replaced byworkspace_query(SQL). UpdateenabledToolsand prompts. - Access. Declare
workspace.accesson an Agent (none,read,writeorreadWrite), orworkspace.defaultAccesson a Crew to set the default for its agents. A crew that declares nothing behaves as before. - Configuration.
spec.artifacts.queryEnginein KubemootConfig and the chart valueartifacts.queryEngineareworkspace.queryEngine.kubemootImage: artifactAccessin an MCPServer isworkspaceAccess, andspec.images.artifactAccess(chart valueimages.artifactAccess) isworkspaceAccess. - Image. The
artifact-accessimage isworkspace-access. Change any crew value that names it. - Crew names. In a crew chart, the MCPServer
artifact-readops-mcpisworkspace-mcp, the egress keyartifact-readops-mcpisworkspace-mcp, and the valuesmcpServers.artifactReadOpsandmcpServers.artifactAccessaremcpServers.workspace. The old values still render for one release. - Environment. Variables that start with
ARTIFACT_start withWORKSPACE_(for exampleARTIFACT_BUCKETisWORKSPACE_BUCKET). - Mount. The
/artifactsdirectory is/workspacein prompts and sandbox code. The old path works for one release because the same volume is also mounted at/artifacts. - Storage. The NATS bucket
kubemoot_discussion_artifactsis nowkubemoot_workspace. Data in the old bucket is temporary and expires within 48 hours, so nothing needs copying. Start the upgrade with no discussion running. - CLI and API.
kmctl conversation artifactiskmctl conversation workspace(the old command warns), and the dashboard and gateway routes end in/workspace. JSON output fromkmctlgainsworkspacekeys, and the oldartifactkeys stay for one release. - 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.