Community on Kubemoot

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Contributions are welcome: bug reports, ideas, documentation fixes, tests, and code. This page is the process. The Development Guide covers the repository layout and how to build and test each component.

Report a bug or request a feature

Not sure it is a bug, or have a question? Open a Discussion.
Found a defect? Open an issue on the repo where you found it, using the bug report template. If the Quickstart itself failed, use the quickstart-failed template; it asks for what is needed to reproduce a fresh-cluster run.
Have an idea for a feature? Start in Discussions, so the shape of the idea can settle before anyone writes code. A maintainer turns it into an issue when the work is clear. The feature request template works too when you already know what you want.
Larger or cross-cutting change? Open an issue titled Proposal: <summary> describing the problem, the approach, the alternatives, and what it touches (CRDs, runtime, dashboard, crews). See Governance.

Open a pull request

Fork the repository you want to change, clone your fork, and branch off main.

Development Guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers the repository layout and how to build and test each component. The process for issues, ideas, and pull requests is on the Contributing page; the conventions a change is expected to follow are summarized at the end of this one.

Repositories

Repository	What it holds
kubemoot	The operator, agent runtime, dashboard, MCP components, and the component docs
crews	Packaged crews as Helm charts
kmctl	The command-line tool
vscode-crewforge	CrewForge for VS Code
kubemoot-docs	This site: the Hugo and Docsy shell and the cross-cutting chapters

Layout of the kubemoot repository

Component	Path	Language / stack
Operator	`operator/`	Go, controller-runtime, kubebuilder CRDs
Agent runtime	`agent-runtime/`	Java / Quarkus + LangChain4j (GraalVM native)
Dashboard	`dashboard/`	SvelteKit
MCP bridge, scheduling and tool servers	`mcp-bridge/`, `scheduling-mcp/`, `artifact-access/`, `code-sandbox/`	Go
MCP gateway	`mcp-gateway/`	Java
Discussion gateway, crew liaison, fitness runner	`discussion-gateway/`, `crew-liaison/`, `fitness-runner/`	Go
Indexer	`indexer/`	Java
Query service	`query-service/`	Python
Quickstart	`quickstart/`	Shell
Integration tests	`k8s/tests/`	Shell

Prerequisites

Go 1.27+ (operator, Go components)
Java 25+ with Gradle (agent runtime, indexer, MCP gateway)
Node.js 26+ (dashboard)
kubectl and helm (v3.8+, for OCI charts)
Access to a Kubernetes cluster; kind works for the quickstart

Build and test

Every change ships with tests. Run the suite for the component you touched.

Governance

Mon, 01 Jan 0001 00:00:00 +0000

Kubemoot is an independent open-source project. Its governance is small and deliberately simple, and this page states how it works today.

Maintainers

Maintainer	Role
Jonathan Johnson	Maintainer

Write access to the repositories in the kubemoot organization is limited to the maintainers. Everyone else contributes through forks and pull requests.

How decisions are made

The maintainer decides. Day-to-day changes are decided in the pull request or issue where they come up. Changes that affect the API (the CRDs), the consensus protocol, or how components fit together are discussed in the open first, so the reasoning is on record:

Code of Conduct

Mon, 01 Jan 0001 00:00:00 +0000

Kubemoot follows the Contributor Covenant, version 2.1. It applies in every project space: GitHub issues, pull requests, and Discussions, and any other place where someone represents the project in public.

The full text lives in one place, the CODE_OF_CONDUCT.md file in the organization’s .github repository. GitHub shows it on every repository in the organization, so it is not copied into each one.

The short version

Be respectful of differing opinions, viewpoints, and experience.
Give and accept constructive feedback gracefully.
Take responsibility for mistakes and learn from them.
Focus on what is best for the community, not only for you.

Harassment, trolling, insulting comments, and publishing others’ private information are not acceptable.

Security

Mon, 01 Jan 0001 00:00:00 +0000

Reporting a vulnerability

Report vulnerabilities privately to security@kubemoot.org. That address is only for vulnerability reports; send every other question to moot@kubemoot.org or GitHub Discussions. Do not open a public issue, Discussion, or pull request for a security report. Where a repository’s Security tab offers Report a vulnerability, GitHub’s private reporting works too.

Include what is affected (repository and version), the steps to reproduce, and what an attacker gains. The project acknowledges reports within a reasonable period and coordinates disclosure with the reporter before any public announcement. With a single maintainer, that is best effort, not a guaranteed response time.

Releases and Versioning

Mon, 01 Jan 0001 00:00:00 +0000

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

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:, and refactor: bump the patch number, feat: bumps the minor, and feat!:, fix!:, or a BREAKING CHANGE footer bumps the major. See Contributing.
Tags the commit with a candidate version, X.Y.Z-rc.N.
Builds the candidate image and chart and pushes them to the maintainers’ own registry. Candidates are not published publicly and are not meant for installation.

Promotion. When a candidate has passed its tests, a maintainer runs the Promote Release workflow. It 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, tags the candidates’ commits with the final version, runs the quickstart against the published chart, and creates the GitHub Release with notes generated from the conventional commits. Promotion defaults to a dry run that plans the release and publishes nothing.