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)
• Commit each implementation phase separately. For multi-phase milestones, commit at each phase boundary with tests passing. Each commit should be self-contained and independently describable. Phase-by-phase commits surface issues early, keep history bisectable, and make later review and reflection far easier than one large end-of-milestone commit.

Repo Initialization

• Rename default branch immediately after git init. git init still creates master on many systems despite main being the modern default. Run git branch -m master main (or configure init.defaultBranch = main globally) before first push — otherwise git push -u origin main fails with src refspec main does not match any. Bake this into any project-bootstrap script.

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
• Copy hook scripts into .git/hooks/; don't symlink. A symlinked hook resolves to the working-tree file, which changes on every branch switch — hooks then run stale (or wrong-branch) logic. Use an install-hooks.sh that copies the source script into .git/hooks/, and re-run it whenever the source changes.
• Document the sync-then-commit sequence when hooks require an up-to-date main. If a pre-commit hook requires local main to match origin/main, the commit silently blocks when local main is even one commit behind. Standard sequence: git checkout main && git pull --ff-only && git checkout <branch> && git rebase main.

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

Separate Data Repos from Code Repos for GitOps Controllers

When a GitOps controller watches a git repo for declarative state (zone files, policy documents, config blobs), keep that data in a repo separate from the controller's app code. Mixing the two means every data change triggers CI builds (container rebuilds, test runs) for no reason, and pollutes the code repo's history with non-code churn.

Separation yields:

• Pure data commits with no CI noise
• Cleaner webhook targeting per-repo
• Independent access control for data editors vs code maintainers
• Simpler rollback semantics — revert a data change without touching the controller image

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
• Prefer internal hostnames for self-hosted Git remotes on the local network. SSH push to a self-hosted Git server through a public/VPS hostname can return kex_exchange_identification: read: Connection reset by peer, especially during heavy agent activity — VPS routes often have connection limits or rate limiting that fail silently under load. On the local network, use the internal hostname in SSH aliases for heavy push workflows; reserve the public hostname for external access or HTTPS. Test with ssh -T <alias> immediately after configuring.

Cross-User Pushes

• Prefer SSH aliases over temp-URL swaps. When a repo is owned by user A but your default SSH key authenticates as user B, configure a dedicated SSH host alias (Host gitea.example.com-userA with matching private key) and use git@gitea.example.com-userA:org/repo.git. Avoid temp-URL-swap (embedding an HTTPS token in the remote URL, pushing, then resetting) — it's clunky, prone to shell-quoting errors, and leaks tokens into reflog/history.
• API-created repos need the SSH user as a 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. Applies to Gitea, GitHub, and any platform where API auth and SSH auth use different identities.

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.
• Reset shallow clones against HEAD, not origin/main. A single-branch shallow clone (--depth N) creates no remote-tracking refs for other branches, so origin/main does not exist unless main is the branch being cloned. Init/reset logic that does git reset --hard origin/main fails on any other branch. Reset against HEAD instead — it is branch-agnostic and works regardless of which branch was shallow-cloned.

Cross-Remote Hygiene for Multi-Remote Projects

When a project has divergent remotes (e.g., local Gitea with granular commits + GitHub with squash-merged PRs), histories diverge and naive merges explode.

• Never git merge <remote>/<branch> --allow-unrelated-histories — it produces 50+ mass conflicts across unrelated files.
• Import specific files instead: git checkout <remote>/<branch> -- <specific-files> brings those paths in as a normal local change.
• Always diff after a bulk checkout. git checkout from a remote silently overwrites locally-modified files with older remote versions with zero warning. Run git status and review each touched file before staging; restore with git checkout HEAD -- <file> if an unwanted overwrite happened.
• After an upstream PR squash-merge, reset — don't rebase — local branches to main. Rebase against a squashed history leaves phantom commits; a clean git reset --hard origin/main on the local branch is correct.

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

Rebase Before Manual Commits to a CI-Auto-Bumped Branch/Deploy Repo

When CI auto-commits back to the same branch you push to — [skip ci] dependency-sync commits, deploy manifests with an image newTag bumped by a build job, ArgoCD chore: deploy commits — your push races those bots. A push made just after your fetch is rejected as non-fast-forward (! [rejected] ... (fetch first)), and on a deploy repo the running image can silently lag origin/main by many builds with no obvious error.

• Standard sequence: git pull --rebase origin <branch> && git push origin <branch>. Rebase (not merge) keeps history linear against the bot commits.
• Expect conflicts in bot-managed files (dependency manifests, version pins, image tags). Resolve by taking the higher/newer value.
• This race also fires immediately after you trigger a dependency-sync that CI auto-commits — pull-rebase before pushing your own follow-up.

Gitea: Use workflow_dispatch, Not repository_dispatch, for API-Triggered Builds

On Gitea (observed 1.25.x), POST /api/v1/repos/<org>/<repo>/dispatches (the repository_dispatch trigger) returns 404 and never fires the workflow. Trigger builds instead via POST /api/v1/repos/<org>/<repo>/actions/workflows/<file>.yaml/dispatches with body {"ref":"main","inputs":{...}} (the workflow_dispatch trigger).

Also don't point a Gitea webhook at the /dispatches endpoint to chain builds: Gitea webhooks send the full push-event body (not {"event_type": ...}, which the endpoint ignores) and carry no auth header (so the call 401s). Chain builds from an in-CI dispatch step instead.

PR Governance on Protected Branches

• Don't bypass a required_approvals gate to unblock automation. On a branch protected with required_approvals: N, do not self-approve a PR through a second bot account/token to let automation merge. That approval gate is a deliberate production-publish guardrail set by the repo owner; bypassing it defeats its intent. Leave the PR open for a human to approve. (This is distinct from a merge-whitelist misconfiguration, which is a config bug to fix — an approval gate is intentional.)
• Promote a targeted change with a feature branch, never by merging the whole staging branch. When a protected main requires approvals and you need to publish one targeted change, do not push/merge the entire integration branch (e.g. staging → main) — that promotes all accumulated changes at once. Push a feature branch containing only the targeted change and open a PR against main. Keeps the diff reviewable and prevents accidental bulk promotion.