Git for Platform Work Basics

This page covers the day-to-day Git and GitHub moves for running a Kubernetes manifest repo: branching, pull requests, required checks, and CODEOWNERS. It is aimed at platform engineers who edit YAML that reconciles into a cluster.

Prerequisites

• Git 2.40+ and a GitHub repository you can push branches to.
• kubectl (matching Kubernetes 1.36.2) for local validation.
• kubeconform for offline manifest schema checks.
• The GitHub CLI gh for opening PRs from the terminal.

# macOS quick install
brew install git gh kubectl kubeconform

Basic Examples

1. Clone the manifest repo and inspect layout

Start from a clean clone so your local state matches the default branch.

git clone https://github.com/org/cluster-manifests.git
cd cluster-manifests
git switch main && git pull --ff-only

• --ff-only refuses to create a surprise merge commit if history diverged.
• Manifest repos usually split base/, overlays/, and clusters/.
• Never edit directly on main; it should be protected.
• Confirm your remote with git remote -v before pushing.

2. Create a topic branch per change

One branch per logical change keeps PRs small and reviewable.

git switch -c raise-checkout-replicas

• Name branches after intent, not tickets alone, so history reads well.
• Small branches merge faster and are easier for CODEOWNERS to review.
• Rebase on main before opening the PR to avoid stale diffs.
• Delete the branch after merge to keep the remote tidy.

3. Edit a manifest and validate locally

Change one field and validate before you push.

# overlays/prod/checkout/replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout
spec:
  replicas: 4

kubeconform -strict -kubernetes-version 1.36.2 overlays/prod/checkout/replicas-patch.yaml

• -strict rejects unknown fields, catching typos like replias.
• Pin -kubernetes-version to the cluster's minor to match its schema.
• Validating locally saves a slow CI round trip.
• Kustomize users can run kubectl kustomize overlays/prod | kubeconform -strict -.

4. Commit with a clear, scoped message

A good message states the component and the effect.

git commit -am "checkout: raise prod replicas 3 -> 4 for peak load"

• Prefix with the component (checkout:) so git log is scannable.
• Explain the why in the body when the change is not obvious.
• One commit per branch is fine; squash on merge if you prefer.
• Avoid mixing a replica bump and an image change in one commit.

5. Open a pull request

The PR is the unit of change for the cluster.

git push -u origin raise-checkout-replicas
gh pr create --fill --base main

• --fill uses your commit message as the PR title and body.
• The PR triggers required checks before anyone can merge.
• Keep the description focused; reviewers should grasp the blast radius fast.
• Link the incident or change request if one exists.

6. Read the required status checks

Required checks are the gate between a PR and the cluster.

gh pr checks

• Green checks typically include schema validation and policy dry-run.
• A failed conftest check means a policy rejected the manifest.
• You cannot merge until required checks pass on a protected branch.
• Re-push a fix; checks re-run automatically on the new commit.

7. Merge and let the reconciler apply

Merging updates the source of truth, and the GitOps controller does the rest.

gh pr merge --squash --delete-branch

• Squash merge keeps main history linear and revert-friendly.
• Argo CD or Flux detects the new commit and reconciles the cluster.
• Watch the rollout with kubectl rollout status deploy/checkout.
• If it misbehaves, revert the merge commit to roll back.

Intermediate Examples

8. Configure branch protection and CODEOWNERS

Protection plus CODEOWNERS makes the right people approve the right paths.

# CODEOWNERS at repo root
/overlays/prod/          @org/sre
/platform/networkpolicy/ @org/platform-security

# Branch protection for main (conceptual)
required_pull_request_reviews:
  require_code_owner_reviews: true
  required_approving_review_count: 1
required_status_checks:
  strict: true
  contexts: [kubeconform, conftest]
enforce_admins: true

• require_code_owner_reviews makes CODEOWNERS approval mandatory, not advisory.
• strict: true forces branches to be up to date before merge.
• enforce_admins stops admins from bypassing the rules quietly.
• Store this as code where possible (Terraform or the GitHub API) for auditability.

9. Add a manifest validation check in Actions

Run the same validation CI that the cluster expects, on every PR.

# .github/workflows/validate.yaml
name: validate
on:
  pull_request:
    paths: ["overlays/**", "base/**"]
jobs:
  kubeconform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          curl -sL -o kubeconform.tar.gz \
            https://github.com/yannh/kubeconform/releases/latest/download/kubeconform-linux-amd64.tar.gz
          tar xf kubeconform.tar.gz && sudo mv kubeconform /usr/local/bin/
      - run: kubeconform -strict -kubernetes-version 1.36.2 -summary overlays/ base/

• The paths filter runs the check only when manifests change.
• Name this job to match the contexts in branch protection so it becomes required.
• -summary gives a compact pass/fail count in the log.
• Failing the job blocks merge, keeping broken YAML out of main.

10. Promote a change between environments

Promotion is a small PR that bumps a pinned image digest in the prod overlay.

git switch -c promote-checkout-2.4.0
# set image to registry/checkout@sha256:... in overlays/prod
git commit -am "checkout: promote 2.4.0 to prod (digest pinned)"
gh pr create --fill --base main

• Pin to an image digest, not a floating tag, so prod is reproducible.
• The prod path triggers the SRE CODEOWNERS review automatically.
• Keep staging and prod as separate overlays so promotion is an explicit step.
• The reconciler applies the merged prod overlay; watch the rollout to confirm.

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).