Contributing¶

For contributors — how to set up, build and submit changes. Not needed to use the operator.

Thank you for your interest in contributing to the Home Assistant Operator! Community contributions — bug reports, feature requests, and code — are very welcome.

How Can I Help?¶

The best first step is always opening an Issue on GitHub:

• Bug reports — found something broken? Include steps to reproduce, operator version, and HA version
• Feature requests — describe the use case, not just the feature
• Questions — something unclear in the docs or behavior? Open a GitHub Discussion

Every submission helps shape the project.

Pull Request Guidelines¶

1. Fork & PR — work on your fork and pick the right target branch (see Branching & Releases):
2. new functionality (feat:, anything spec.alpha.* / v1alpha1, breaking changes) → target dev
3. bug fixes for the current release (fix:, docs:, perf:) → target main
4. One PR = one change — don't mix unrelated changes
5. Tests required — make test must pass; new behavior needs new tests
6. Linting — make lint must report no errors
7. Security — run make security-check before submitting (CI blocks PRs with known vulnerabilities)
8. Commit style — use Conventional Commits: feat/fix/docs/test/chore/refactor/perf/ci(scope): message

Development Setup¶

Prerequisites¶

• Go 1.26+
• Docker or Podman
• kubectl
• k3d (for local cluster testing)
• pre-commit (for commit hooks)

# Clone and enter the repo
git clone https://github.com/przemekhys/homeassistant-operator
cd homeassistant-operator

# Install pre-commit hooks (required — CI enforces the same checks)
pre-commit install
pre-commit install --hook-type commit-msg

# Download envtest binaries used by unit tests
make setup-envtest

Common Workflows¶

# After modifying types in api/v1/*.go — always run this first
make manifests generate && make fmt vet

# Run unit tests
make test

# Build the binary
make build

# Run the controller locally against the current kubeconfig cluster
make run

Code Quality¶

make fmt vet          # Format + vet
make lint             # Lint (report only)
make lint-fix         # Lint + auto-fix
make security-check   # govulncheck — required before PR
make dupl-check       # Detect duplicate code

Local Cluster with k3d¶

make k3d-create       # Create a local k3d cluster
make install          # Install CRDs
make docker-build IMG=controller:latest && make k3d-load && make deploy
kubectl logs -n homeassistant-operator-system -l control-plane=controller-manager -f
make k3d-delete       # Tear down

Pre-commit Hooks¶

This project uses pre-commit to catch issues before they reach CI.

Hooks run automatically on every git commit:

# Run all hooks manually against every file
pre-commit run --all-files

# Run a specific hook
pre-commit run golangci-lint --all-files

# Update hook versions to latest
pre-commit autoupdate

Adding a New CRD¶

1. kubebuilder create api --group ha --version v1 --kind YourResource
2. Define types in api/v1/yourresource_types.go
3. make manifests generate && make fmt vet
4. Write unit tests in internal/controller/yourresource_controller_test.go
5. Implement internal/controller/yourresource_controller.go
6. Commit API types and generated files together in one commit

Documentation¶

Documentation is organised by what the reader came to do, and the build is strict about links, anchors and orphaned pages. Before adding or moving a page, read writing documentation — it says which section a page belongs in and what shape it takes.

make docs-serve     # live preview at http://127.0.0.1:8000
make docs-verify    # the same gate CI runs

Code of Conduct¶

Be respectful and constructive. This is a small project and we want to keep a friendly atmosphere.