Git GitHub CI/CD

Git & GitHub Practices

How to use version control effectively with AI agents. Branching, commits, pre-commit hooks, CI/CD, and automation patterns that prevent mistakes.

# commit_discipline

# Good
fix: timezone conversion dropping DST offset in March
feat: add Gmail noise filtering for newsletters

# Bad
fixed stuff
update
wip

One feature or fix per commit. Don't bundle unrelated changes.

Commit after every working change. Don't accumulate.

Never git add . — add specific files to avoid secrets or binaries.

Check size first — git diff --cached --stat. No files over 1MB.

# branching_and_prs

Never edit main directly. Main auto-deploys on many projects. Direct edits = untested code in production.

git checkout main && git pull
git checkout -b fix/descriptive-name
# make changes, commit
git push -u origin fix/descriptive-name

# Create PR
gh pr create --title "Fix: descriptive name" --body "What and why"

# After CI passes → merge
# For public repos → squash merge

Branch prefixes: fix/, feature/, refactor/, docs/. One feature per PR. Clear title + description. No secrets in diff.

# pre_commit_hooks

Automated checks that run before every commit. Catch bugs before they enter the repo.

What it checks

Undefined Python names (ruff F821) — catches NameError before runtime

How it works

Checks staged content only (not working tree) — validates exactly what's being committed

Architecture: One shared hook file, all repos delegate to it. Change the rules once, every repo picks it up instantly.

# ci_cd

GitHub Actions run on every push and PR. Only check for real bugs — never style issues.

1. ruff F821 — undefined names

2. py_compile — syntax validation

3. pytest — unit tests (if present)

4. node --check — JS syntax in HTML

Rule: If CI fails on a style issue (unused import, formatting), fix the CI — not the code. CI gates real bugs only.

# gitignore

Any file with credentials must be gitignored. Provide a .example template instead.

# Always ignore
config.json          # Secrets, API keys
*.db                 # SQLite databases
venv/                # Virtual environments
__pycache__/         # Python cache
node_modules/        # Node dependencies
.wrangler/           # Cloudflare cache

# Always provide
config.json.example  # Template with placeholder values

# automation

Git events trigger automated workflows — no manual intervention needed.

GitHub Webhooks

Push to main → webhook fires → VPS auto-pulls the repo

Post-Merge Hooks

After pull, run sync scripts — update docs, refresh caches

Pre-Commit Hooks

Before commit, validate code — catch undefined names

CI/CD

On push/PR, run tests — gate broken code from merging

# lessons_learned

Secrets committed → credential rotation needed. Always gitignore config files.

Direct main edit → production broke. Always branch first.

No pre-commit hook → undefined name passed locally, crashed in production.

Large file pushed → GitHub rejected. Check git diff --cached --stat first.