From 1a3195a950fc42372c463827dc97085afbf0745d Mon Sep 17 00:00:00 2001
From: Fran Leustek <fran@devzero.io>
Date: Fri, 9 Jan 2026 14:50:38 +0100
Subject: [PATCH 1/5] add pre-commit

---
 .github/CONTRIBUTING.md          | 46 +++++++++++++++++++++++++++-----
 .github/workflows/pre-commit.yml | 45 +++++++++++++++++++++++++++++++
 .pre-commit-config.yaml          | 30 +++++++++++++++++++++
 Makefile                         | 22 ++++++++++-----
 4 files changed, 129 insertions(+), 14 deletions(-)
 create mode 100644 .github/workflows/pre-commit.yml
 create mode 100644 .pre-commit-config.yaml

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index f6e9e1ab..4446e824 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -15,6 +15,7 @@ By participating in this project, you agree to abide by our [Code of Conduct](.g
 - [Commit Message Guidelines](#commit-message-guidelines)
 - [Testing](#testing)
 - [Linting](#linting)
+- [Pre-Commit Hooks](#pre-commit-hooks)
 - [Documentation](#documentation)
 - [Component-Specific Guidelines](#component-specific-guidelines)
 - [Backporting Changes](#backporting-changes)
@@ -38,19 +39,19 @@ If you discover a bug, have a feature request, or need to provide feedback, plea
 
 When you're ready to contribute code:
 
-1. **Fork and Clone**  
+1. **Fork and Clone**
    Fork the repository and clone it to your local machine.
-2. **Create a Branch**  
+2. **Create a Branch**
    Create a feature branch from the appropriate base branch (typically `main`).
-3. **Make Changes**  
+3. **Make Changes**
    Implement your changes, ensuring they adhere to the project's coding standards.
-4. **Run Tests**  
+4. **Run Tests**
    Verify that all tests pass locally. Refer to the testing section below for more details.
-5. **Update Documentation**  
+5. **Update Documentation**
    Update or add documentation as needed in the corresponding directories.
-6. **Commit and Push**  
+6. **Commit and Push**
    Write clear commit messages that reference the related issue (e.g., "fix: Description of fix").
-7. **Open a Pull Request**  
+7. **Open a Pull Request**
    Submit a pull request (PR) with a detailed description of your changes and link any related issues.
 
 ---
@@ -106,6 +107,37 @@ Linting rules are configured in `.golangci.yml` at the repository root. The conf
 
 ---
 
+## Pre-Commit Hooks
+
+We use pre-commit hooks to catch issues before code is committed.
+
+### Install pre-commit
+
+```bash
+python3 -m pip install --user pre-commit
+```
+
+### Install required Go tools
+
+```bash
+go install golang.org/x/tools/cmd/goimports@v0.30.0
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.2
+```
+
+### Install hooks
+
+```bash
+make pre-commit-install
+```
+
+### Run hooks manually
+
+```bash
+pre-commit run --all-files
+```
+
+---
+
 ## Documentation
 
 Contributions to documentation are highly valued. If you find any documentation gaps or errors:
diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
new file mode 100644
index 00000000..811523c3
--- /dev/null
+++ b/.github/workflows/pre-commit.yml
@@ -0,0 +1,45 @@
+name: pre-commit
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  merge_group:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    name: pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: "go.mod"
+          cache: true
+
+      - name: Add Go bin to PATH
+        run: echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+
+      - name: Install pre-commit
+        run: python -m pip install --upgrade pip pre-commit
+
+      - name: Install Go tools
+        run: |
+          go install golang.org/x/tools/cmd/goimports@v0.30.0
+          go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.2
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files --show-diff-on-failure
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 00000000..14f968bc
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,30 @@
+default_stages:
+  - pre-commit
+
+repos:
+  - repo: local
+    hooks:
+      - id: gofmt
+        name: gofmt
+        entry: gofmt -w
+        language: system
+        types: [go]
+      - id: goimports
+        name: goimports
+        entry: goimports -w
+        language: system
+        types: [go]
+      - id: golangci-lint
+        name: golangci-lint
+        entry: golangci-lint run --timeout=5m
+        language: system
+        pass_filenames: false
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-json
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
diff --git a/Makefile b/Makefile
index a78ef5a8..e507567b 100644
--- a/Makefile
+++ b/Makefile
@@ -60,7 +60,7 @@ DAKR_URL ?= https://dakr.devzero.io
 # PROMETHEUS URL for metrics collection
 PROMETHEUS_URL ?= http://prometheus-dz-prometheus-server.$(DEVZERO_MONITORING_NAMESPACE).svc.cluster.local:80
 # TARGET_NAMESPACES for limiting collection to specific namespaces (comma-separated)
-TARGET_NAMESPACES ?= 
+TARGET_NAMESPACES ?=
 # COLLECTION_FILE is used to control the collectionpolicies.
 COLLECTION_FILE ?= env_configmap.yaml
 # ENV_CONFIGMAP_FILE is used to control the zxporter-manager deployment.
@@ -162,6 +162,14 @@ lint: golangci-lint ## Run golangci-lint linter
 lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes
 	$(GOLANGCI_LINT) run --fix
 
+.PHONY: pre-commit-install
+pre-commit-install: ## Install pre-commit hooks.
+	pre-commit install --install-hooks
+
+.PHONY: pre-commit
+pre-commit: ## Run pre-commit on all files.
+	pre-commit run --all-files
+
 GITVERSION ?= $(shell git describe --tags 2>/dev/null || echo "v0.0.0-$(shell git rev-parse --short HEAD)")
 
 ifeq ($(shell echo $(GITVERSION) | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+"),)
@@ -354,7 +362,7 @@ build-installer: manifests generate kustomize yq ## Generate a consolidated YAML
 	# @cat $(METRICS_SERVER) >> $(DIST_INSTALL_BUNDLE)
 	# @echo "# ----- END METRICS SERVER -----" >> $(DIST_INSTALL_BUNDLE)
 	@echo "---" >> $(DIST_INSTALL_BUNDLE)
-	
+
 	@echo "[INFO] Append zxporter-manager to the installer bundle"
 	@cd config/manager && $(KUSTOMIZE) edit set image controller=${IMG}
 
@@ -396,11 +404,11 @@ HELM_CHART_PACKAGE_DIR := helm-chart/packages
 helm-chart-build: helm ## Build and package the Helm chart
 	@echo "[INFO] Building Helm chart..."
 	@mkdir -p $(HELM_CHART_PACKAGE_DIR)
-	
+
 	# Update chart version and appVersion
 	@$(YQ) eval '.version = "$(VERSION)"' -i $(HELM_CHART_DIR)/Chart.yaml
 	@$(YQ) eval '.appVersion = "$(VERSION)"' -i $(HELM_CHART_DIR)/Chart.yaml
-	
+
 	# Package the chart
 	@$(HELM) package $(HELM_CHART_DIR) --destination $(HELM_CHART_PACKAGE_DIR)
 	@echo "[INFO] Helm chart packaged successfully"
@@ -681,7 +689,7 @@ install-buf: ## Install buf if not already installed
 		echo "$(BUF_BINARY_NAME) is already installed."; \
 	fi
 
-# (for local dev) Get metadata to generate a Dakr client. 
+# (for local dev) Get metadata to generate a Dakr client.
 .PHONY: generate-proto
 generate-proto: install-buf ## Fetch latest Dakr protobuf
 	@PROTO_DIR="$(PWD)/proto"; \
@@ -693,7 +701,7 @@ generate-proto: install-buf ## Fetch latest Dakr protobuf
 	cp "$(DAKR_MPA_PROTO)" "$$PROTO_DIR/api/v1"; \
 	find "$$PROTO_DIR" -type f -name "*.yaml" -exec perl -pi -e 's|github.com/devzero-inc/services/dakr/gen|github.com/devzero-inc/zxporter/gen|g' {} +; \
 	buf build "$(DAKR_DIR)" --path "$(DAKR_METRICS_COLLECTOR_PROTO)" --path "$(DAKR_CLUSTER_PROTO)" -o "$$PROTO_DIR"/dakr_proto_descriptor.bin; \
-	buf generate --include-imports "$$PROTO_DIR"/dakr_proto_descriptor.bin; 
+	buf generate --include-imports "$$PROTO_DIR"/dakr_proto_descriptor.bin;
 	buf generate --verbose --include-imports --timeout=5m .
 
 # Lima Verification
@@ -714,7 +722,7 @@ verify-local: setup-lima
 	@chmod +x verification/verify_local.sh
 	@./verification/verify_local.sh $(LIMA_INSTANCE)
 
-# for local, this will be something like: 
+# for local, this will be something like:
 #         make verify-e2e CLUSTER_CONTEXT=kind-zxporter-e2e NAMESPACE=devzero-zxporter
 .PHONY: verify-e2e
 verify-e2e: ## Run E2E verification on a Kind or Cloud cluster

From 3b20f6e757341797745658b04b402a3eeab7f364 Mon Sep 17 00:00:00 2001
From: Fran Leustek <fran@devzero.io>
Date: Fri, 9 Jan 2026 15:21:41 +0100
Subject: [PATCH 2/5] update pre-commit setup with local tools

---
 .github/CONTRIBUTING.md | 27 +++++++++------------------
 .gitignore              |  2 ++
 .pre-commit-config.yaml |  6 ++++--
 Makefile                | 26 ++++++++++++++++++++++----
 4 files changed, 37 insertions(+), 24 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 4446e824..05ffc8e7 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -111,30 +111,21 @@ Linting rules are configured in `.golangci.yml` at the repository root. The conf
 
 We use pre-commit hooks to catch issues before code is committed.
 
-### Install pre-commit
+### Quick setup
 
-```bash
-python3 -m pip install --user pre-commit
-```
+Run: `make pre-commit-setup` (bootstraps `.venv`, installs Go tools into `.tools/bin`, and installs hooks).
 
-### Install required Go tools
+### Run hooks manually
 
-```bash
-go install golang.org/x/tools/cmd/goimports@v0.30.0
-go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.2
-```
+Run: `make pre-commit`.
 
-### Install hooks
+### Troubleshooting
 
-```bash
-make pre-commit-install
-```
-
-### Run hooks manually
+If setup fails, you can run the steps individually:
 
-```bash
-pre-commit run --all-files
-```
+- Run: `make pre-commit-install-tool`.
+- Run: `make pre-commit-tools`.
+- Run: `make pre-commit-install`.
 
 ---
 
diff --git a/.gitignore b/.gitignore
index c151c339..28ca7beb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,6 +29,8 @@ config/**/charts
 *~
 
 .claude
+.venv
+.tools
 
 /zxporter-netmon
 *.o
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 14f968bc..1f80550c 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -11,12 +11,12 @@ repos:
         types: [go]
       - id: goimports
         name: goimports
-        entry: goimports -w
+        entry: ./.tools/bin/goimports -w
         language: system
         types: [go]
       - id: golangci-lint
         name: golangci-lint
-        entry: golangci-lint run --timeout=5m
+        entry: ./.tools/bin/golangci-lint run --timeout=5m --new-from-rev=HEAD
         language: system
         pass_filenames: false
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -26,5 +26,7 @@ repos:
       - id: end-of-file-fixer
       - id: check-json
       - id: check-yaml
+        args: ["--allow-multiple-documents"]
+        exclude: ^helm-chart/.*/templates/
       - id: check-added-large-files
         args: ["--maxkb=1024"]
diff --git a/Makefile b/Makefile
index e507567b..b0642246 100644
--- a/Makefile
+++ b/Makefile
@@ -162,13 +162,31 @@ lint: golangci-lint ## Run golangci-lint linter
 lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes
 	$(GOLANGCI_LINT) run --fix
 
+PRE_COMMIT ?= .venv/bin/pre-commit
+
+.venv/bin/pre-commit:
+	python3 -m venv .venv
+	.venv/bin/pip install --upgrade pip pre-commit
+
 .PHONY: pre-commit-install
-pre-commit-install: ## Install pre-commit hooks.
-	pre-commit install --install-hooks
+pre-commit-install: .venv/bin/pre-commit ## Install pre-commit hooks.
+	$(PRE_COMMIT) install --install-hooks
 
 .PHONY: pre-commit
-pre-commit: ## Run pre-commit on all files.
-	pre-commit run --all-files
+pre-commit: .venv/bin/pre-commit ## Run pre-commit on all files.
+	$(PRE_COMMIT) run --all-files
+
+.PHONY: pre-commit-tools
+pre-commit-tools: ## Install Go tools needed by pre-commit.
+	@mkdir -p .tools/bin
+	GOBIN="$(PWD)/.tools/bin" go install golang.org/x/tools/cmd/goimports@v0.30.0
+	GOBIN="$(PWD)/.tools/bin" go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.2
+
+.PHONY: pre-commit-install-tool
+pre-commit-install-tool: .venv/bin/pre-commit ## Install pre-commit into a local virtualenv.
+
+.PHONY: pre-commit-setup
+pre-commit-setup: pre-commit-install-tool pre-commit-tools pre-commit-install ## Install pre-commit, tools, and hooks.
 
 GITVERSION ?= $(shell git describe --tags 2>/dev/null || echo "v0.0.0-$(shell git rev-parse --short HEAD)")
 

From 3ef302aeabc0064e5e1d378db801974d7d6eac68 Mon Sep 17 00:00:00 2001
From: Fran Leustek <fran@devzero.io>
Date: Fri, 9 Jan 2026 15:23:26 +0100
Subject: [PATCH 3/5] update contributing.md

---
 .github/CONTRIBUTING.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 05ffc8e7..aac36c46 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -127,6 +127,12 @@ If setup fails, you can run the steps individually:
 - Run: `make pre-commit-tools`.
 - Run: `make pre-commit-install`.
 
+<!-- todo? remove scope later when all old lint errors are fixed -->
+
+### Lint scope
+
+`golangci-lint` runs in pre-commit with `--new-from-rev=HEAD` to report only issues introduced by your changes.
+
 ---
 
 ## Documentation

From 948121230ad96a3221d121e603b45c5fae36c87a Mon Sep 17 00:00:00 2001
From: Fran Leustek <fran@devzero.io>
Date: Fri, 9 Jan 2026 17:44:16 +0100
Subject: [PATCH 4/5] update local pre commit

---
 .github/CONTRIBUTING.md | 11 ++++++-----
 .pre-commit-config.yaml |  2 +-
 Makefile                |  4 ++--
 3 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index aac36c46..62e01657 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -110,15 +110,20 @@ Linting rules are configured in `.golangci.yml` at the repository root. The conf
 ## Pre-Commit Hooks
 
 We use pre-commit hooks to catch issues before code is committed.
+Local hooks are optional; by default nothing runs on commit unless you install hooks yourself.
 
 ### Quick setup
 
-Run: `make pre-commit-setup` (bootstraps `.venv`, installs Go tools into `.tools/bin`, and installs hooks).
+Run: `make pre-commit-setup` (bootstraps `.venv` and installs Go tools into `.tools/bin`).
 
 ### Run hooks manually
 
 Run: `make pre-commit`.
 
+### Optional: enable pre-commit on every commit
+
+Run: `make pre-commit-install`.
+
 ### Troubleshooting
 
 If setup fails, you can run the steps individually:
@@ -129,10 +134,6 @@ If setup fails, you can run the steps individually:
 
 <!-- todo? remove scope later when all old lint errors are fixed -->
 
-### Lint scope
-
-`golangci-lint` runs in pre-commit with `--new-from-rev=HEAD` to report only issues introduced by your changes.
-
 ---
 
 ## Documentation
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 1f80550c..32c29529 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -16,7 +16,7 @@ repos:
         types: [go]
       - id: golangci-lint
         name: golangci-lint
-        entry: ./.tools/bin/golangci-lint run --timeout=5m --new-from-rev=HEAD
+        entry: ./.tools/bin/golangci-lint run --timeout=5m
         language: system
         pass_filenames: false
   - repo: https://github.com/pre-commit/pre-commit-hooks
diff --git a/Makefile b/Makefile
index b0642246..e094ae0d 100644
--- a/Makefile
+++ b/Makefile
@@ -169,7 +169,7 @@ PRE_COMMIT ?= .venv/bin/pre-commit
 	.venv/bin/pip install --upgrade pip pre-commit
 
 .PHONY: pre-commit-install
-pre-commit-install: .venv/bin/pre-commit ## Install pre-commit hooks.
+pre-commit-install: .venv/bin/pre-commit ## Install pre-commit hooks (optional).
 	$(PRE_COMMIT) install --install-hooks
 
 .PHONY: pre-commit
@@ -186,7 +186,7 @@ pre-commit-tools: ## Install Go tools needed by pre-commit.
 pre-commit-install-tool: .venv/bin/pre-commit ## Install pre-commit into a local virtualenv.
 
 .PHONY: pre-commit-setup
-pre-commit-setup: pre-commit-install-tool pre-commit-tools pre-commit-install ## Install pre-commit, tools, and hooks.
+pre-commit-setup: pre-commit-install-tool pre-commit-tools ## Install pre-commit and tools (hooks are optional).
 
 GITVERSION ?= $(shell git describe --tags 2>/dev/null || echo "v0.0.0-$(shell git rev-parse --short HEAD)")
 

From aaaa3253dc61bb6f4a5196a0a4c71c06d308d0c5 Mon Sep 17 00:00:00 2001
From: Fran Leustek <fran@devzero.io>
Date: Fri, 9 Jan 2026 17:48:30 +0100
Subject: [PATCH 5/5] update pre-commit path

---
 .github/workflows/pre-commit.yml | 7 ++++---
 Makefile                         | 4 ++--
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
index 811523c3..8f6b4c89 100644
--- a/.github/workflows/pre-commit.yml
+++ b/.github/workflows/pre-commit.yml
@@ -31,15 +31,16 @@ jobs:
           cache: true
 
       - name: Add Go bin to PATH
-        run: echo "$(go env GOPATH)/bin" >> $GITHUB_PATH
+        run: echo "${{ github.workspace }}/.tools/bin" >> $GITHUB_PATH
 
       - name: Install pre-commit
         run: python -m pip install --upgrade pip pre-commit
 
       - name: Install Go tools
         run: |
-          go install golang.org/x/tools/cmd/goimports@v0.30.0
-          go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.2
+          mkdir -p .tools/bin
+          GOBIN="${{ github.workspace }}/.tools/bin" go install golang.org/x/tools/cmd/goimports@v0.30.0
+          GOBIN="${{ github.workspace }}/.tools/bin" go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.2
 
       - name: Run pre-commit
         run: pre-commit run --all-files --show-diff-on-failure
diff --git a/Makefile b/Makefile
index e094ae0d..523b206a 100644
--- a/Makefile
+++ b/Makefile
@@ -173,8 +173,8 @@ pre-commit-install: .venv/bin/pre-commit ## Install pre-commit hooks (optional).
 	$(PRE_COMMIT) install --install-hooks
 
 .PHONY: pre-commit
-pre-commit: .venv/bin/pre-commit ## Run pre-commit on all files.
-	$(PRE_COMMIT) run --all-files
+pre-commit: pre-commit-tools .venv/bin/pre-commit ## Run pre-commit on all files.
+	PATH="$(PWD)/.tools/bin:$$PATH" $(PRE_COMMIT) run --all-files
 
 .PHONY: pre-commit-tools
 pre-commit-tools: ## Install Go tools needed by pre-commit.