Proyecto
Contribuir
KubeBolt es open source con licencia Apache 2.0. Cómo preparar el repositorio y cómo entran los cambios.
En esta página
KubeBolt se publica con licencia Apache 2.0. El repositorio es clm-cloud-solutions/kubebolt; su CONTRIBUTING.md es la versión de referencia de esta página. Son bienvenidos los reportes de bugs, las correcciones de documentación, las nuevas reglas de insights, las integraciones y las mejoras de la UI. Para funcionalidades y cambios más grandes, abre primero un issue o una discusión.
Entorno de desarrollo
Necesitas Go 1.26 (la línea go de apps/api/go.mod; la CI fija 1.26.11) y
Node 22, y un clúster de Kubernetes en tu kubeconfig (kind, k3d, Docker
Desktop, minikube o uno remoto).
# Clonar
git clone https://github.com/clm-cloud-solutions/kubebolt.git
cd kubebolt
# La API en :8080 y Vite en :5173 en una sola terminal; Ctrl+C detiene los dos
make dev
O ejecútalos por separado:
# Backend: puerto 8080
cd apps/api && go run ./cmd/server --kubeconfig ~/.kube/config
# Frontend: puerto 5173, hace de proxy de /api y /ws hacia el backend
cd apps/web && npm install && npm run dev
Variantes útiles:
make dev-clean/make dev-api-clean: arrancan con un kubeconfig vacío, para trabajar en los estados sin clústeres y de espera del agente.KUBEBOLT_ADMIN_PASSWORD=...fija la contraseña del admin; si no, se genera una y se imprime en la terminal.KUBEBOLT_AUTH_ENABLED=falsese salta el inicio de sesión, pero también el almacén embebido: sin historial de insights, hallazgos de seguridad, ajustes ni conversaciones de Kobi.- Copia
.env.examplea.envpara activar funciones opcionales (Kobi, notificaciones…);make devlo carga. Todas las variables están en Variables de entorno. - Para las métricas históricas, arranca VictoriaMetrics con
cd deploy && docker compose up -d victoriametricsy exportaKUBEBOLT_METRICS_STORAGE_URL=http://localhost:8428. make kind-testbedinstala metrics-server y un workload de demostración en tu clúster kind actual;make agent-devconstruye la imagen del agente, la despliega ahí y sigue sus logs.
Antes de hacer push, ejecuta la misma comprobación que ejecuta la CI:
make ci-local
Ejecuta go build, go vet y go test -race para apps/api, npm test y
npm run build para apps/web (Vitest no comprueba tipos; el build sí) y los
tests de las reglas de alerta con promtool en Docker. Para cambios en el
agente, ejecuta también cd packages/agent && go test ./....
Para compilar el binario único de producción, con el frontend embebido:
make build-binary
# Genera apps/api/kubebolt
Ramas y pull requests
Dos ramas de larga duración:
develop: la rama de integración. El trabajo diario va contra esta.main: lo que se publica.developse fusiona en ella en cada versión.
Trabaja en una rama de tema con un nombre que diga lo que hace (feat/…,
fix/…, docs/…, chore/…), creada desde develop, y abre la pull request
contra develop. Las pull requests de versión son la excepción: van de
develop → main.
Limita la pull request a un solo cambio, incluye tests para los cambios de comportamiento y explica en la descripción qué se rompe si el cambio está mal. Actualiza en la misma pull request la documentación que describe lo que cambiaste. Los cambios de UI llevan una captura de pantalla o una grabación corta. La CI tiene que estar en verde antes de la revisión.
Mensajes de commit
Conventional Commits, con el área afectada como scope y un asunto que diga qué cambió y no qué archivos se movieron:
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
Tipos habituales: feat, fix, docs, chore, refactor. Varios scopes se
separan con comas (fix(copilot,nav):). Un cambio incompatible lleva un !
después del scope.
CI
GitHub Actions se ejecuta en cada push y pull request a main y develop:
- Backend:
go build ./...,go vet ./...y despuésgo test ./... -race -count=1(Go 1.26.11, ubuntu-latest) - Frontend:
npm ci,npm testy despuésnpm run build(Node 22, ubuntu-latest) - Reglas de alerta: las reglas de alerta del chart contra sus tests unitarios,
con
promtool
En paralelo corren CodeQL y un escaneo de imagen en cada pull request.
Reportar un problema de seguridad
No abras un issue ni una pull request públicos para una vulnerabilidad. Repórtala de forma privada en kubebolt.io/security: la página tiene la dirección de reporte, qué entra y qué no en el alcance, nuestros compromisos de respuesta y los términos de divulgación coordinada (una fecha de publicación acordada contigo, hasta 90 días desde el reporte). PGP disponible a petición.
Estructura del repositorio
kubebolt/
├── apps/api/ # Backend en Go
├── apps/web/ # Frontend en React
├── packages/agent/ # El agente del clúster: línea 1.x, chart y changelog propios
├── packages/proto/ # Definiciones Protobuf del canal del agente
├── packages/shared/ # Utilidades Go compartidas
├── deploy/ # Charts de Helm (kubebolt + kubebolt-agent), Docker Compose, Homebrew/krew
├── docs/ # architecture.md, guides/, integrations/, releases/, COMPATIBILITY.md
├── tests/ # Fixtures de pruebas end-to-end
├── go.work # Workspace de Go
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CLAUDE.md # Notas paquete por paquete para Claude Code
└── README.md
Dónde proponer cambios en el producto
Los reportes de bugs y las pull requests van en el repositorio. La dirección de las funcionalidades se discute mejor en kubebolt.io/feedback: una persona real lee cada mensaje, y alimenta el roadmap público.