Create pre-commit-framework-migration.md via n8n
This commit is contained in:
parent
1f6ca01138
commit
8ec8c76b37
189
Tech/Projects/pre-commit-framework-migration.md
Normal file
189
Tech/Projects/pre-commit-framework-migration.md
Normal file
@ -0,0 +1,189 @@
|
||||
---
|
||||
project: pre-commit-framework-migration
|
||||
type: project-plan
|
||||
status: active
|
||||
path: Tech/Projects
|
||||
tags:
|
||||
- homelab
|
||||
- tooling
|
||||
- git
|
||||
- ansible
|
||||
- security
|
||||
created: 2026-05-03
|
||||
updated: 2026-05-03
|
||||
---
|
||||
# pre-commit framework migration
|
||||
|
||||
## Goal
|
||||
|
||||
Replace the raw `.git/hooks/pre-commit` bash script (currently shared via
|
||||
`core.hooksPath`) with the [pre-commit framework](https://pre-commit.com),
|
||||
and adopt it as the standard for all new repos. Codify a curated set of
|
||||
checks that catch the mistakes most likely to bite a solo homelab operator
|
||||
working across Python, Go, Ansible, and YAML-heavy infra repos.
|
||||
|
||||
## Why
|
||||
|
||||
The current raw hook works but has limits:
|
||||
|
||||
- not version-controlled (lives in `.git/hooks/`, not tracked)
|
||||
- single-purpose (vault encryption check only)
|
||||
- adding more checks means growing a bash script
|
||||
- no portability across machines without re-running the `core.hooksPath`
|
||||
setup
|
||||
|
||||
The framework solves all four: config lives in `.pre-commit-config.yaml` at
|
||||
the repo root, gets committed, and gives access to a large ecosystem of
|
||||
pre-built hooks.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- Install `pre-commit` framework on dev machines
|
||||
- Migrate the existing ansible-vault check from raw bash to a framework hook
|
||||
- Curate a default `.pre-commit-config.yaml` template covering Python, Go,
|
||||
Ansible, YAML, and secret-detection
|
||||
- Document the install/onboarding flow as the standard for new repos
|
||||
- Decide how the framework coexists with (or replaces) the current
|
||||
`core.hooksPath` setup
|
||||
- Add the template to project scaffolding so new repos start with it
|
||||
pre-wired
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Migrating every existing repo today (do them as they're touched)
|
||||
- Full CI integration (pre-commit can also run in GitHub Actions, but
|
||||
that's a follow-up)
|
||||
- Replacing `zero-check` or other post-generation validation skills
|
||||
|
||||
## Decisions to confirm
|
||||
|
||||
- **Coexistence with `core.hooksPath`** — once the framework is in a repo,
|
||||
its `pre-commit install` will overwrite `.git/hooks/pre-commit` for that
|
||||
repo. Need to decide: leave `core.hooksPath` as a fallback for repos
|
||||
without `.pre-commit-config.yaml`, or unset it once all active repos are
|
||||
migrated?
|
||||
- **Vault check location** — keep the bash script in-repo at
|
||||
`scripts/check-vault.sh` (referenced as a `local` hook), or rewrite as a
|
||||
tiny standalone repo and pin like other framework hooks?
|
||||
- **Template repo or scaffold-generated** — does the default
|
||||
`.pre-commit-config.yaml` live in a `homelab-templates` repo for
|
||||
`web_fetch` access, or get generated by the project scaffolding tool?
|
||||
|
||||
## Curated check list
|
||||
|
||||
Grouped by category. Each is a separate hook entry; opt in per repo by
|
||||
what's actually relevant.
|
||||
|
||||
### Universal (every repo)
|
||||
|
||||
- `trailing-whitespace` — strip trailing spaces
|
||||
- `end-of-file-fixer` — ensure files end with a newline
|
||||
- `check-merge-conflict` — block commits with unresolved conflict markers
|
||||
- `check-added-large-files` — block accidental large file commits (default
|
||||
500KB)
|
||||
- `mixed-line-ending` — enforce LF
|
||||
- `detect-private-key` — block committing SSH/TLS private keys
|
||||
|
||||
### Secrets & sensitive data
|
||||
|
||||
- `detect-secrets` (Yelp) — broader secret scanning beyond just private
|
||||
keys; catches AWS keys, API tokens, high-entropy strings
|
||||
- `gitleaks` — alternative or complement; well-maintained, fast
|
||||
- **Custom: ansible-vault encryption check** — port of the existing bash
|
||||
hook
|
||||
|
||||
### YAML / config
|
||||
|
||||
- `check-yaml` — basic YAML syntax validation
|
||||
- `yamllint` — style + structure (line length, indentation, truthy values)
|
||||
- `check-json` — JSON syntax
|
||||
- `check-toml` — TOML syntax
|
||||
|
||||
### Python
|
||||
|
||||
- `ruff` — lint + format in one tool (replaces flake8, isort, black for
|
||||
most cases)
|
||||
- `ruff-format` — formatter
|
||||
- `mypy` — optional, type-checking (heavier; opt in per project)
|
||||
|
||||
### Go
|
||||
|
||||
- `go-fmt` — gofmt enforcement
|
||||
- `go-vet` — basic static analysis
|
||||
- `golangci-lint` — broader linting (opt in per project)
|
||||
|
||||
### Ansible-specific
|
||||
|
||||
- **Custom: ansible-vault encryption check** (existing logic, ported)
|
||||
- `ansible-lint` — full Ansible playbook/role linting
|
||||
- `yamllint` (already covered above, but Ansible repos lean on it heavily)
|
||||
|
||||
### Shell scripts
|
||||
|
||||
- `shellcheck` — catches common bash bugs and bad patterns
|
||||
- `shfmt` — formatter for shell scripts
|
||||
|
||||
### Markdown / docs
|
||||
|
||||
- `markdownlint` — style/structure for `.md` files
|
||||
- (Skip if it gets noisy on Obsidian-flavored markdown — the project notes
|
||||
use front-matter and Obsidian syntax that vanilla markdownlint may complain
|
||||
about.)
|
||||
|
||||
## Migration path
|
||||
|
||||
1. Pick one active repo as the pilot — likely the new project where this
|
||||
conversation started.
|
||||
2. `pip install pre-commit` (or `uv tool install pre-commit`) on the dev
|
||||
machine.
|
||||
3. Drop in a starter `.pre-commit-config.yaml` covering universal + secrets
|
||||
+ ansible + relevant language checks.
|
||||
4. Port the vault check as a `local` hook pointing at
|
||||
`scripts/check-vault.sh`.
|
||||
5. `pre-commit install` to wire it up.
|
||||
6. `pre-commit run --all-files` to flush out anything the existing code
|
||||
violates.
|
||||
7. Iterate on the config until baseline is clean.
|
||||
8. Once stable, copy `.pre-commit-config.yaml` to the template location
|
||||
(TBD — see decisions).
|
||||
9. Decide on `core.hooksPath` — leave or unset.
|
||||
10. Add `pre-commit install` to the project scaffolding flow so new repos
|
||||
get it automatically.
|
||||
|
||||
## Tasks
|
||||
|
||||
- [ ] Confirm decisions: coexistence with `core.hooksPath`, vault check
|
||||
location, template hosting
|
||||
- [ ] Install `pre-commit` framework on dev machines
|
||||
- [ ] Pilot on one active repo
|
||||
- [ ] Port vault encryption check as a `local` hook
|
||||
- [ ] Build default `.pre-commit-config.yaml` template covering universal +
|
||||
secrets + Python + Go + Ansible + YAML
|
||||
- [ ] Run `pre-commit run --all-files` on pilot, fix or ignore findings
|
||||
- [ ] Document the install/onboarding flow (README section or standalone
|
||||
doc)
|
||||
- [ ] Decide whether to keep or unset `core.hooksPath`
|
||||
- [ ] Migrate active repos one by one as they're touched
|
||||
- [ ] Add template to scaffolding tool or `homelab-templates` repo
|
||||
- [ ] Evaluate whether to add CI run of `pre-commit run --all-files` on PRs
|
||||
(follow-up)
|
||||
|
||||
## Open questions
|
||||
|
||||
- Does `pre-commit` play well with the `zero-check` skill, or is there
|
||||
overlap to resolve?
|
||||
- For Obsidian-flavored markdown, is `markdownlint` worth the noise or skip
|
||||
entirely?
|
||||
- Should `mypy` be in the default Python config, or opt-in per project?
|
||||
|
||||
## References
|
||||
|
||||
- pre-commit docs: https://pre-commit.com
|
||||
- Hook list: https://pre-commit.com/hooks.html
|
||||
- Existing raw hook: stored at `~/.config/git-hooks/pre-commit` (per
|
||||
`core.hooksPath` setup)
|
||||
|
||||
|
||||
...sent from Jenny & Travis
|
||||
Loading…
Reference in New Issue
Block a user