Contributing

Skipper is open source under the Apache 2.0 license. Contributions are welcome.

Development setup

Prerequisites

• Go 1.22+
• Node.js 20+
• Docker (for local testing)

Clone and build

git clone https://github.com/labb-consulting/skipper
cd skipper

# Build the CLI
cd kip && go build -o kip . && cd ..

# Run the console in dev mode
cd console && npm install && npm run dev && cd ..

# Run the docs site
cd docs && npm install && npm run dev && cd ..

Running tests

# Go tests (kip, console-api, gateway)
cd kip && go test ./...
cd console-api && go test ./...
cd gateway && go test ./...

# Console type checking
cd console && npm run type-check

Project structure

Directory	Language	Purpose
kip/	Go	CLI tool
console/	Vue 3 + TypeScript	Web dashboard
console-api/	Go	REST API for the console
gateway/	Go	kipper.run subdomain proxy
docs/	VitePress	This documentation

CRD architecture

Skipper manages workloads through Custom Resource Definitions (getkipper.com/v1alpha1). When a user deploys an app, creates a service, or adds a function, the handler creates a Custom Resource. A controller-runtime reconciler watches these CRs and ensures the underlying Kubernetes resources (Deployments, StatefulSets, Services, Ingresses) match the desired spec.

CRD	Reconciles into
App	Deployment + Service + Ingress + Secrets
Service	StatefulSet + headless Service + credentials Secret
Function	Deployment + Service + KEDA HTTPScaledObject + Ingress
Project	Namespaces + shared storage PVCs
Job	CronJob or Job
Volume	PersistentVolumeClaim

Key directories:

• console-api/api/v1alpha1/: CRD type definitions
• console-api/controllers/: reconcilers (one per CRD)
• console-api/handlers/: REST API handlers that create CRs
• deploy/crds/: generated CRD YAML manifests

When adding a new feature, decide whether it needs a new CRD (owns Kubernetes resources) or can be added as a field on an existing one. Use controller-gen to regenerate manifests after changing types.

Code conventions

Go

• Table-driven tests with testify
• Error wrapping with context: fmt.Errorf("installing k3s: %w", err)
• Unexported by default, only export what is used outside the package
• Interfaces belong in the package that uses them
• All exported types and functions need godoc comments

Vue / TypeScript

• Composition API with <script setup lang="ts">, never Options API
• No any, define proper types
• Pinia stores with loading and error state
• Tailwind utility classes only, no inline styles
• lucide-vue-next for icons

Commits

Format: type: short description

Types: feat:, fix:, docs:, style:, refactor:, test:, chore:, perf:

Branches

Format: prefix/short-description

Prefixes: feature/, bugfix/, hotfix/, refactor/, docs/, test/

PR guidelines

• New features require unit tests covering the happy path and at least two error cases
• Bug fixes require a test that would have caught the bug
• Documentation changes are required in the same PR as feature changes
• Every example must use realistic names, not foo or bar

Licensing

All contributions must be compatible with the Apache 2.0 license. No GPL dependencies. MIT and Apache 2.0 only.