Skip to content

SnowOps GitOps Branching Standard

Asset: C4  |  Tier: Quick-Win [QW]  |  Milestone: M1  |  Ownership: [CA] (client-adopted)

This is the canonical branching model SnowOps applies to every repository under its automation: the snowops-automation repo itself, every client repo provisioned by B1 snowops-onboarder, and the client-repo template (C4) that clients fork on day one.

The rules below are enforced by branch protection (configured by B1) and checked at PR time by pr-template-check.yml (R1). They are not aspirational — a non-conforming PR cannot merge.

1. Branches

Branch Purpose Lifetime
main Single source of truth. Every deploy ships from main. Always green. Permanent. Protected.
feat/<scope>-<slug> New functionality. One feature per branch. Until merged; auto-delete on merge.
fix/<scope>-<slug> Bug fixes against main. Until merged.
chore/<scope>-<slug> Tooling, deps, refactors with no behaviour change. Until merged.
sec/<scope>-<slug> Security fixes. May skip review SLA via break-glass label (R3, M4). Until merged.
compliance/<scope>-<slug> Policy, evidence, audit work. Requires Nidhi review. Until merged.

Scope is the affected area (auth, network, crm, docs, …). Slug is two-to-four words, hyphenated. Example: feat/network-private-endpoint-eso.

release/* and hotfix/* branches are not used. Production rolls forward from main; reverts are PRs against main.

2. Commits

  • Style: Conventional Commits.
  • Allowed types: feat fix chore sec compliance infra test docs.
  • Scope (optional but encouraged): feat(network): ..., sec(auth): ....
  • Breaking change: feat(network)!: ... or BREAKING CHANGE: footer.
  • Subject: imperative, lowercase, ≤ 72 chars, no trailing period.

Each commit must be individually buildable — if it lands on main by itself, CI must stay green. This is required for git bisect and for the per-asset revert pattern.

3. Pull requests

Rule Why
One concern per PR. Smaller diffs = faster review + safer revert.
PR template (R1) must be filled in. Forces "Summary / Test plan / Risk / Rollback" thinking.
At least one CODEOWNER approval. Configured in .github/CODEOWNERS.
All required checks green (D2 + C1 plan). No "merge with red checks".
Squash merge only. main history is one commit per PR; easy to revert.
Auto-delete branch on merge. Stale branches are a source of confusion.
No force-pushes to main ever. Branch protection enforces.
Stale branches > 30 days flagged. Either land it or close it.

PR title

Same Conventional Commit format as commits — the squash-merge commit on main inherits the PR title verbatim.

Draft PRs

Open as draft while you're still working. CI runs on draft PRs but reviewers are not pinged. Move to "ready for review" only when the template is complete.

4. Protection rules (enforced by B1)

main requires:

  • Pull request before merging (no direct push, including admins).
  • ≥ 1 approving review from a CODEOWNER.
  • Stale approvals dismissed on new commits.
  • Required status checks (declared per stack):
  • pre-commit-fast
  • checkov tfsec trivy-fs gitleaks conftest
  • terraform-plan for every stack in the repo
  • pr-template-check
  • Require branches up-to-date before merging.
  • Linear history.
  • Conversations resolved before merging.
  • Signed commits (for sec/* and compliance/* branches).

For client repos, B1 applies the rules above plus:

  • Environment protection on production (manual approval + restricted reviewers).
  • Required deployment-environment success for any apply to prod.

5. Tags and releases

  • Module releases (M3+): modules/<cloud>/<name>/v<MAJOR>.<MINOR>.<PATCH> per F11.
  • Application releases: apps/<name>/v<MAJOR>.<MINOR>.<PATCH>.
  • No floating tags. No latest tag. Consumers pin by ref.

6. Reverts

Reverting a merged PR is itself a PR:

git checkout -b fix/revert-<original-pr-slug>
git revert -m 1 <merge-commit-sha>

The revert PR follows the same template + review rules as any other PR. It is not a shortcut around CODEOWNER approval.

7. Quick adoption checklist

For a client repo brought onto this standard:

  • main is the default branch.
  • Branch protection rules above applied (B1 does this; manual fallback in docs/runbooks/test/C4.md).
  • .github/CODEOWNERS, .github/PULL_REQUEST_TEMPLATE.md, and .github/workflows/pr-template-check.yml copied from templates/client-repo/.
  • Pre-commit installed (pre-commit install --install-hooks).
  • One throwaway PR opened and merged to verify all checks fire.

When all five boxes are ticked, the repo is C4-conformant.

See also: §2 Architectural Principles — "GitOps as Source of Truth".