Project
Contributing
KubeBolt is open source under the Apache 2.0 license. How to set up the repo, and how changes get in.
On this page
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.26 (the go line of apps/api/go.mod; CI pins 1.26.11) 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.KUBEBOLT_AUTH_ENABLED=falseskips login, but also the embedded store: no insight history, security findings, settings or Kobi conversations.- Copy
.env.exampleto.envto enable optional features (Kobi, notifications…);make devloads it. Every variable is in Environment variables. - For historical metrics, start VictoriaMetrics with
cd deploy && docker compose up -d victoriametricsand exportKUBEBOLT_METRICS_STORAGE_URL=http://localhost:8428. make kind-testbedinstalls metrics-server and a demo workload into your current kind cluster;make agent-devbuilds the agent image, deploys it there and follows its logs.
Before pushing, run the same gate CI runs:
make ci-local
It runs go build, go vet and go test -race for apps/api, npm test
and npm run build for apps/web (Vitest does not type-check; the build
does), and the alert-rule tests with promtool in Docker. For agent changes,
also run cd packages/agent && go test ./....
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.developis 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): golang.org/x/net v0.60.0 for CVE-2026-78669
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 ./..., thengo test ./... -race -count=1(Go 1.26.11, ubuntu-latest) - Frontend:
npm ci,npm test, thennpm run build(Node 22, ubuntu-latest) - Alert rules: the chart’s alert rules against their unit tests, with
promtool
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
├── CODE_OF_CONDUCT.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.