Git workflow and versioning

Git Workflow and Versioning

Overview

Git is the control plane of DevOps. Infrastructure code, application code, pipeline definitions, and (in GitOps) the desired state of production itself all live in Git. Sloppy Git practice doesn't just make ugly history — it makes unauditable production.

Main is always releasable. Work happens in short-lived branches, merges through reviewed pull requests, and every commit on main passes CI.

History is documentation. A commit message answers "why does this change exist?" six months from now, at 3 AM, during an incident.

When to Use

• Starting any change (branching strategy)
• Committing work (message conventions, atomic commits)
• Opening or reviewing pull requests
• Tagging and publishing releases
• Resolving merge conflicts
• Configuring repository protection rules

The Standard Workflow

main (protected, always green)
  │
  ├── git checkout -b feat/add-redis-ha
  │     ├── commit: "feat(redis): add sentinel configuration"
  │     ├── commit: "test(redis): add failover integration test"
  │     └── push → open PR → CI runs → review → squash or merge commit
  │
  └── git tag -a v1.4.0 -m "Release 1.4.0"  (on main, after merge)

# 1. Sync and branch
git checkout main && git pull
git checkout -b feat/short-description        # or fix/, chore/, docs/, refactor/

# 2. Work in small, atomic commits
git add -p                                     # stage hunks, review as you go
git commit                                     # message per Conventional Commits

# 3. Keep up with main (rebase your branch, never merge main INTO it)
git fetch origin
git rebase origin/main

# 4. Push and open the PR
git push -u origin feat/short-description
gh pr create --fill                            # or the GitLab/Azure DevOps equivalent

Rules:

• One logical change per branch. One PR does one thing.
• Commits are atomic: each one builds and passes tests on its own.
• Never force-push to shared branches. Force-push to your own PR branch only with --force-with-lease.
• Rebase your feature branch onto main; do not merge main into your feature branch — it inverts history and buries the actual change.

Conventional Commits

<type>(<scope>): <imperative summary ≤ 72 chars>

[optional body: what and why, not how]

[optional footer: BREAKING CHANGE:, Refs: #123]

Type	When
feat	New behavior or capability
fix	Bug fix
refactor	Code change with no behavior change
perf	Performance improvement
test	Adding/fixing tests only
docs	Documentation only
build	Build system or dependencies
ci	Pipeline/workflow changes
chore	Tooling, formatting, no production impact
revert	Reverts a previous commit

Examples:

feat(terraform): add remote state backend with locking
fix(ansible): make nginx handler idempotent on Debian 12
ci(github-actions): pin third-party actions by SHA
docs(runbooks): add redis failover procedure
feat(api)!: drop support for v1 auth tokens

Why it matters (not aesthetics): Conventional Commits drive automated changelogs, semantic-release version bumps, and git log --oneline that reads like a changelog during incident review.

Semantic Versioning and Releases

MAJOR.MINOR.PATCH — e.g., 1.4.2:

• MAJOR — breaking changes (feat!: or BREAKING CHANGE:)
• MINOR — new backward-compatible features (feat:)
• PATCH — backward-compatible fixes (fix:)

git tag -a v1.4.2 -m "Release 1.4.2"
git push origin v1.4.2

Rules:

• Tags are created on main, annotated (-a), and pushed explicitly.
• Versions are immutable. v1.4.2 never moves. A botched release gets v1.4.3, not a re-tag.
• Every deployed artifact (image tag, package version) is traceable to a Git tag or commit SHA.
• Changelogs are generated from commit history (git-cliff, semantic-release, release-please), not hand-written.

Pull Requests and Reviews

A mergeable PR has:

1. A small diff. Target ~100–400 lines. Bigger PRs get rubber-stamped, not reviewed.
2. A description that explains why. What problem, what approach, what alternatives were rejected.
3. Green CI. No exceptions, no "merge and fix main after."
4. At least one approval from someone who didn't write it.
5. No unresolved threads. "I'll fix it later" means a linked follow-up issue, or it means no.

Review norms:

• Review within one working day — stale PRs rot.
• Label comments: Nit (optional), Suggestion (consider), Blocker (must fix).
• Review the code, not the person. "This query scans the table" not "you wrote a bad query."

Branch Protection (non-negotiable on main)

Minimum protection set for main/master:

• Require pull request before merging (no direct pushes — admins included)
• Require status checks to pass (CI green)
• Require at least 1 approving review
• Require conversation resolution before merging
• Block force pushes and branch deletion
• Require linear history (rebase or squash merges) — optional but recommended
• Signed commits where the org requires them

If anyone on the team can push directly to main, you do not have a workflow; you have a race condition.

Conflict Resolution

git fetch origin
git rebase origin/main
# conflict appears
git status                          # see conflicted files
# edit files: choose/merge the correct sides
git add <resolved-files>
git rebase --continue
# or bail out entirely:
git rebase --abort

Rules:

• Resolve conflicts on your branch, never by merging main into it.
• If you don't understand both sides of a conflict, stop and ask the other author. Guessing creates semantic bugs that compile fine.
• After resolving, re-run tests. Conflict resolution is a code change.

Common Rationalizations

Rationalization	Reality
"It's a tiny fix, I'll push straight to main"	The protection exists for tiny fixes too — tiny fixes take down production. Open the PR; it takes two minutes.
"I'll fix the commit messages before release"	You won't, and now the changelog generator can't classify your changes. Write them right the first time.
"Rebase is dangerous, I'll just merge main in"	Merging main into feature branches inverts causality and makes history unreadable. Learn rebase on a small branch; it's a core skill.
"Force push is fine, nobody else is on this branch"	Use --force-with-lease. Always. It refuses to clobber work you haven't seen.
"I'll version it when it's stable"	Version from day one (0.1.0). "Unversioned" artifacts can't be rolled back or traced.
"This PR is urgent, reviews can come after"	Urgent changes are exactly the ones that need a second pair of eyes. Use a hotfix process with an expedited review — not zero review.

Red Flags

• Direct pushes to main are possible
• Commit messages like "fix", "changes", "wip", "asdf"
• PRs merged with red CI
• Long-lived feature branches measured in weeks
• Merge commits that merge main into feature branches
• Force pushes without --force-with-lease
• Tags that get deleted and re-created
• Nobody can answer "which commit is running in production?"

Verification

• Every commit on main arrived via a reviewed PR with green CI
• All commit messages follow Conventional Commits
• Releases are annotated tags on main following SemVer
• Branch protection rules are enabled and include admins
• git log --oneline main reads like a changelog
• The commit running in production is identifiable and tagged
• Changelog/release notes are generated from history, not hand-maintained