Skip to content

Contributing

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 submit a Pull Request against main
  2. One PR = one change — don't mix unrelated changes
  3. Tests required — make test must pass; new behavior needs new tests
  4. Linting — make lint must report no errors
  5. Security — run make security-check before submitting (CI blocks PRs with known vulnerabilities)
  6. 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:

Hook What it checks
gofumpt / goimports Code formatting
golangci-lint Linting
yamllint YAML syntax (Kubernetes manifests)
commitizen Conventional commit message format
gitleaks Accidentally committed secrets
check-yaml / check-merge-conflict General file hygiene 
# 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

Never edit zz_generated.deepcopy.go manually

This file is fully generated by make generate. Manual edits will be overwritten.

Code of Conduct

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