docs/PRE-COMMIT.md
This guide explains how to use pre-commit for local code quality checks and secret scanning in the Astron Agent project.
Pre-commit is a framework for managing and maintaining multi-language pre-commit hooks. In this project, we use it to:
Ensure you have the following installed:
# Install pre-commit using pip
pip install pre-commit
# Or using pipx (recommended for isolated installation)
pipx install pre-commit
# Or using Homebrew (macOS)
brew install pre-commit
# Install pre-commit hooks
pre-commit install
# Install commit-msg hook for commit message validation
pre-commit install --hook-type commit-msg
After installation, pre-commit will automatically run on every git commit.
Once installed, pre-commit runs automatically when you commit:
git add .
git commit -m "feat: add new feature"
# Pre-commit hooks run automatically
If any check fails, the commit will be blocked. Fix the issues and try again.
# Check only staged files
pre-commit run
# Check all files in the repository
pre-commit run --all-files
# Run a specific hook
pre-commit run <hook-id>
# Examples
pre-commit run black --all-files
pre-commit run eslint-check --all-files
pre-commit run gitleaks --all-files
# Update all hooks to latest versions
pre-commit autoupdate
| Hook | Description |
|---|---|
check-yaml | Validate YAML file syntax |
check-json | Validate JSON file syntax |
check-added-large-files | Prevent large files (>1MB) from being committed |
check-merge-conflict | Check for merge conflict markers |
| Hook | Description | Scope |
|---|---|---|
black | Check code formatting | core/agent, core/workflow, core/knowledge, core/plugin |
isort-* | Check import sorting | Per-module (knowledge, workflow, agent, plugin) |
flake8-* | Lint for code issues | Per-module |
mypy-* | Type checking | Per-module |
pylint-* | Code analysis | Per-module |
| Hook | Description | Scope |
|---|---|---|
prettier-check | Check code formatting | console/frontend/src |
eslint-check | Lint for code issues | console/frontend/src |
| Hook | Description | Scope |
|---|---|---|
golangci-lint | Comprehensive linting | core/tenant |
go-fmt-check | Check gofmt formatting | core/tenant |
go-imports-check | Check goimports formatting | core/tenant |
go-vet | Check for suspicious code | core/tenant |
| Hook | Description | Scope |
|---|---|---|
spotless-check | Check Google Java Format | console/backend |
checkstyle | Check code style | console/backend |
| Hook | Description |
|---|---|
gitleaks | Scan for secrets and credentials |
| Hook | Description |
|---|---|
conventional-pre-commit | Validate Conventional Commits format |
Pre-commit runs in check-only mode - it reports issues but does not auto-fix them. Here's how to fix issues for each language:
# Fix formatting with Black
black .
# Fix import sorting with isort
isort .
# Or fix specific directories
cd core/knowledge && black . && isort .
cd console/frontend
# Fix formatting with Prettier
npm run format
# Or
npx prettier --write "src/**/*.{ts,tsx,js,jsx,json,md}"
# Fix linting issues (auto-fixable only)
npx eslint "src/**/*.{ts,tsx}" --fix
cd core/tenant
# Fix formatting
gofmt -w .
goimports -w .
# Or use gofumpt for stricter formatting
gofumpt -w .
cd console/backend
# Fix formatting with Spotless
mvn spotless:apply
The pre-commit configuration is in .pre-commit-config.yaml at the project root.
# Skip specific hooks for a single commit
SKIP=black,eslint-check git commit -m "feat: urgent fix"
# Skip all pre-commit hooks
git commit --no-verify -m "feat: emergency commit"
Warning: Use
--no-verifysparingly. It bypasses all quality checks.
Pre-commit automatically detects which files changed and runs only relevant hooks. For example:
.py files only triggers Python hooks.ts files only triggers TypeScript hooks# Reinstall hooks
pre-commit uninstall
pre-commit install
pre-commit install --hook-type commit-msg
# Clear pre-commit cache
pre-commit clean
# Run with verbose output for debugging
pre-commit run --all-files --verbose
Ensure the required tools are installed and in your PATH:
# Check Python tools
python3 -m black --version
python3 -m isort --version
python3 -m flake8 --version
# Check Node tools
npx prettier --version
npx eslint --version
# Check Go tools
golangci-lint --version
gofmt -help
# Check Java tools
mvn --version
Some hooks (like Java checks) can be slow. They run only when relevant files change.
If gitleaks flags a false positive (e.g., example API keys in documentation), you can:
.gitleaksignoreIf you encounter issues:
.pre-commit-config.yaml configurationRun pre-commit before pushing: Even though hooks run on commit, running pre-commit run --all-files before pushing ensures all files are checked.
Keep hooks updated: Run pre-commit autoupdate periodically to get the latest hook versions.
Don't skip hooks: Avoid using --no-verify unless absolutely necessary. If a check is consistently problematic, discuss with the team.
Fix issues immediately: Don't accumulate technical debt. Fix formatting and linting issues as they arise.
Use CI as backup: Our CI pipeline also runs these checks, so any missed issues will be caught before merge.