Contributing — KubeBolt Docs

KubeBolt is Apache 2.0. The repository is clm-cloud-solutions/kubebolt; its CONTRIBUTING.md is the authoritative version of this page. Bug reports, documentation fixes, new insight rules, integrations and UI improvements are all welcome. For features and larger changes, open an issue or a discussion first.

Development Setup

Requires Go 1.25+ and Node 22 (CI builds on Go 1.26.6 and Node 22), and a Kubernetes cluster in your kubeconfig (kind, k3d, Docker Desktop, minikube or a remote one).

# Clone
git clone https://github.com/clm-cloud-solutions/kubebolt.git
cd kubebolt

# API on :8080 and Vite on :5173 in one terminal; Ctrl+C stops both
make dev

Or run them separately:

# Backend — port 8080
cd apps/api && go run ./cmd/server --kubeconfig ~/.kube/config

# Frontend — port 5173, proxies /api and /ws to the backend
cd apps/web && npm install && npm run dev

Useful variants:

make dev-clean / make dev-api-clean — start with an empty kubeconfig, to work on the no-clusters and waiting-for-agent states.
KUBEBOLT_ADMIN_PASSWORD=... sets the admin password; otherwise one is generated and printed to the terminal.
Copy .env.example to .env to enable optional features (Kobi, notifications…); make dev loads it.
For historical metrics, start VictoriaMetrics with cd deploy && docker compose up -d victoriametrics and export KUBEBOLT_METRICS_STORAGE_URL=http://localhost:8428.

Before pushing, run the same gate CI runs:

make ci-local

To build the production single binary, with the frontend embedded:

make build-binary
# Produces apps/api/kubebolt

Branching and pull requests

Two long-lived branches:

develop — the integration branch. Everyday work targets this one.
main — what ships. develop is merged into it at release time.

Work on a topic branch named after what it does — feat/…, fix/…, docs/…, chore/… — branched off develop, and open the pull request against develop. Release pull requests are the exception: they go develop → main.

Keep the pull request scoped to one change, include tests for behaviour changes, and say in the description what breaks if the change is wrong. Update the docs that describe what you changed in the same pull request. UI changes carry a screenshot or a short recording. CI has to be green before review.

Commit messages

Conventional Commits, with the affected area as the scope and a subject that says what changed rather than which files moved:

feat(insights): the lifecycle — episodes, mutes, rule policies, the shift report
fix(api): bound the episode-history pagination conversions before narrowing to int32
docs: OpenShift guide, restricted-v2 web workaround and in-cluster Events timeout
chore(deps): x/crypto v0.55.0 (CVE-2026-56854)

Common types: feat, fix, docs, chore, refactor. Multiple scopes are comma-separated (fix(copilot,nav):). A breaking change carries a ! after the scope.

CI

GitHub Actions runs on push and pull request to main and develop:

Backend: go build ./..., go vet ./..., then go test ./... -race -count=1 (Go 1.26.6, ubuntu-latest)
Frontend: npm ci, npm test, then npm run build (Node 22, ubuntu-latest)

CodeQL and a pull-request image scan run alongside.

Reporting a security issue

Do not open a public issue or pull request for a vulnerability. Report it privately at kubebolt.io/en/security — the page has the reporting address, what is and is not in scope, our response commitments, and the coordinated-disclosure terms (a publication date agreed with you, up to 90 days from the report). PGP is available on request.

Repository Structure

kubebolt/
├── apps/api/          # Go backend
├── apps/web/          # React frontend
├── packages/agent/    # The cluster agent — own 1.x release line, chart and changelog
├── packages/proto/    # Protobuf definitions of the agent channel
├── packages/shared/   # Shared Go utilities
├── deploy/            # Helm charts (kubebolt + kubebolt-agent), Docker Compose, Homebrew/krew
├── docs/              # architecture.md, guides/, integrations/, releases/, COMPATIBILITY.md
├── tests/             # End-to-end fixtures
├── go.work            # Go workspace
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CLAUDE.md          # Package-by-package notes for Claude Code
└── README.md

Where to propose product changes

Bug reports and pull requests belong in the repository. Feature direction is better discussed at kubebolt.io/en/feedback — a real person reads every message, and it feeds the public roadmap.