| 1 | # Pre-commit / pre-push hooks (local enforcement) |
| 2 | |
| 3 | > Issue: jmservera/SquadScope#544 · Epic: jmservera/SquadScope-Coordinator#33 |
| 4 | > Phase C — local enforcement. Mirrors the CI guardrails so violations are |
| 5 | > caught before they reach a PR. |
| 6 | |
| 7 | The repo ships a [`.pre-commit-config.yaml`](../../.pre-commit-config.yaml) that |
| 8 | runs the same guardrails as CI: |
| 9 | |
| 10 | | Hook | Stage | Mirrors | |
| 11 | |------|-------|---------| |
| 12 | | `ruff` (lint, `--fix`) | commit | Lint workflow (`ruff check .`) | |
| 13 | | `ruff-format` | commit | Lint workflow (`ruff format --check .`) | |
| 14 | | `checkov` | push | Checkov workflow (IaC / Actions scan) | |
| 15 | | `pytest` | push | CI test job (`pytest tests/`) | |
| 16 | | `docker-build` | push | builds a `Containerfile`/`Dockerfile` when present (no-op today) | |
| 17 | |
| 18 | Fast checks (ruff) run on every **commit**; slower checks (checkov, pytest, |
| 19 | docker build) run on **push** to keep the commit loop quick. |
| 20 | |
| 21 | ## Install (one-time) |
| 22 | |
| 23 | ```bash |
| 24 | pip install pre-commit |
| 25 | # Install both hook types so commit-stage and push-stage hooks are wired up: |
| 26 | pre-commit install --hook-type pre-commit --hook-type pre-push |
| 27 | ``` |
| 28 | |
| 29 | To run everything on demand (e.g. before opening a PR): |
| 30 | |
| 31 | ```bash |
| 32 | pre-commit run --all-files |
| 33 | ``` |
| 34 | |
| 35 | ## Tool versions |
| 36 | |
| 37 | Hook versions are **pinned to match CI** so local and CI results agree: |
| 38 | |
| 39 | - `ruff` → `0.15.7` (`rev: v0.15.7`) |
| 40 | - `checkov` → `3.2.533` (`rev: "3.2.533"`) |
| 41 | |
| 42 | `pytest` and the `docker-build` check are `local` hooks that use the |
| 43 | repo-installed tooling (`pip install -r requirements.txt` plus `pytest`). When |
| 44 | you bump a tool version in CI, bump the matching `rev`/dependency in |
| 45 | `.pre-commit-config.yaml` too. |
| 46 | |
| 47 | ## Emergency bypass (hotfixes only) |
| 48 | |
| 49 | ```bash |
| 50 | git commit --no-verify |
| 51 | git push --no-verify |
| 52 | ``` |
| 53 | |
| 54 | `--no-verify` skips **local** hooks only — the CI gates still run on the PR. |
| 55 | Use it only for genuine emergencies and follow up by fixing any skipped |
| 56 | findings. Never weaken or disable a CI gate to land a change: CI must be |
| 57 | correct, not just green. |
| 58 | |
| 59 | ## Notes |
| 60 | |
| 61 | - The `docker-build` hook is a no-op until a `Containerfile`/`Dockerfile` is |
| 62 | added at the repo root, after which it builds the image on push. |
| 63 | - The `checkov` hook only triggers on changes to `.github/workflows/**` or |
| 64 | container files, but always scans the whole repo (`checkov -d .`) to mirror CI. |