best-practices/git-source-control.md

Git & Source Control

Commit Practices

• Use meaningful commit messages; prefer small, focused commits over large batches
• Never commit secrets in plaintext — use SOPS + age or equivalent encryption
• Enable pre-commit hooks where appropriate (secret detection, linting, formatting)

Pre-Commit Hooks

• Block local_secrets/ and similar directories from being committed
• Auto-encrypt files matching .sops.yaml rules that aren't yet encrypted
• Enable with git config core.hooksPath .githooks
• Consider secret detection, linting, and formatting hooks

GitOps Workflow

• All infrastructure changes should be tracked in Git
• No manual changes without corresponding GitOps manifests — anything applied manually (e.g., kubectl apply, helm install) should immediately get a corresponding tracked manifest
• For ArgoCD-managed clusters: edit in Git, push, sync — never edit live resources directly

Remote Conventions

• SSH workflows preferred over HTTPS for Git remotes
• Use SSH config host aliases for multi-user setups (e.g., gitea.example.com-<user>)
• Remote URL format: git@<host-alias>:<org>/<repo>.git
• Optionally push-mirror to GitHub for public visibility

Access and Clone Gotchas

• Org repos require explicit collaborator grants. Don't assume organizational membership implies write access — verify permissions before setting up automation or CI/CD.
• Shallow clones break push operations. git clone --depth 1 is fine for read-only CI jobs, but pipelines that push artifacts, tags, or mirror to other remotes need full clones.

Version Management

• Use the latest stable version of dependencies unless pinned for a reason
• Verify versions from live sources (helm search repo, upstream docs, package registries) — don't rely on memory
• Document the reason in a comment if a version is intentionally pinned below latest
• Check compatibility matrices before upgrading (e.g., Talos ↔ Kubernetes, framework ↔ runtime)

Placeholder Conventions in Template-Heavy Repos

When files contain multiple templating syntaxes (Go templates {{ .var }}, CI variables ${{ }}, Helm {{ }}, etc.), use a distinct placeholder convention for your own substitutions that can't be confused with any templating language:

• Double-underscore: __CUSTOMER_NAME__, __DOMAIN__
• All-caps curly brace (no spaces): {{CUSTOMER_NAME}} (distinct from Go's {{ .Title }} with spaces and dots)

Choose one convention per repo and document it.

Git Worktrees for Parallel Agent Work

When running parallel agents or tasks that modify the same repo:

• Give each task its own branch and worktree (git worktree add .worktrees/<task-id> -b <branch>)
• Tasks with no dependencies branch from HEAD; tasks with one dependency branch from that dependency's branch
• Tasks with multiple dependencies get an octopus merge base branch
• Worktrees share the .git object store — fast creation, minimal disk usage
• Keep containers detached (docker run -d, not --rm) so logs survive for inspection after exit

API-Created Repos Need SSH User as Collaborator

If a repo is created via API token (user A) but pushes use an SSH alias authenticating as user B, user B has no access by default. Add the SSH-authenticating user as admin collaborator via API before the first push. This applies to Gitea, GitHub, and any platform where API auth and SSH auth use different identities.