GitOps + Git Workflow Complete Guide — Branch Strategy, PR Rules, and Deployment Pipelines

# Declarative state definition — Kubernetes Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api-server
          image: ghcr.io/myorg/api-server:v2.4.1
          ports:
            - containerPort: 8080

main ────●─────────────●──────●── (production)
          \           / \    /
release    \    ●────●   \  /
            \  /          \/
develop ─────●──●──●──●───●──●── (integration)
              \  \      /
feature        ●──●────●

main ────●──●──●──●──●── (always deployable)
          \    /  \  /
feature    ●──●    ●──●

main ────●──●──●──●──●──●──●── (every commit is a deploy candidate)
          \/ \/ \/
short     ●  ●  ●  (merged within 1 day)

## Changes

<!-- Briefly describe what was changed and why -->

## Change Type

- [ ] Feature (feature)
- [ ] Bug fix (bugfix)
- [ ] Refactoring (refactor)
- [ ] Infrastructure/config change (infra)
- [ ] Documentation update (docs)

## Testing

- [ ] Unit tests added/updated
- [ ] Integration tests passing
- [ ] Manually verified in local environment

## Checklist

- [ ] Commit messages follow Conventional Commits format?
- [ ] No unnecessary files (logs, temp files) included?
- [ ] Backward compatible with existing APIs?
- [ ] No security-sensitive information (secrets, keys) included?

## Related Issues

Closes #

## Screenshots (for UI changes)

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

# Install
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# commitlint.config.js
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

# Connect with husky Git hook
npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'ci', 'perf', 'revert'],
    ],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100],
  },
}

# argocd/applications/api-server.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api-server
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/k8s-manifests.git
    targetRevision: main
    path: apps/api-server/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true # Auto-remove resources deleted from Git
      selfHeal: true # Auto-correct drift
    syncOptions:
      - CreateNamespace=true
      - PruneLast=true
    retry:
      limit: 3
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

k8s-manifests/
├── apps/
│   ├── api-server/
│   │   ├── base/
│   │   │   ├── deployment.yaml
│   │   │   ├── service.yaml
│   │   │   ├── hpa.yaml
│   │   │   └── kustomization.yaml
│   │   └── overlays/
│   │       ├── dev/
│   │       │   ├── kustomization.yaml
│   │       │   └── patches/
│   │       │       └── replicas.yaml
│   │       ├── staging/
│   │       │   ├── kustomization.yaml
│   │       │   └── patches/
│   │       │       └── replicas.yaml
│   │       └── production/
│   │           ├── kustomization.yaml
│   │           └── patches/
│   │               ├── replicas.yaml
│   │               └── resources.yaml
│   └── web-frontend/
│       ├── base/
│       └── overlays/
├── argocd/
│   ├── applications/
│   │   ├── api-server.yaml
│   │   └── web-frontend.yaml
│   └── projects/
│       └── default.yaml
└── README.md

graph LR
    A[Developer Push] --> B[GitHub Actions CI]
    B --> C{Tests Pass?}
    C -->|Yes| D[Build Container Image]
    C -->|No| E[Failure Notification]
    D --> F[Push Image to GHCR]
    F --> G[Create PR in Manifest Repo]
    G --> H[Auto-merge / Manual Approval]
    H --> I[ArgoCD Detects Change]
    I --> J[Kubernetes Sync]
    J --> K{Health Check}
    K -->|Healthy| L[Deployment Complete]
    K -->|Degraded| M[Auto Rollback]

# .github/workflows/ci-cd.yaml
name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Unit tests
        run: npm run test -- --coverage

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

  build-and-push:
    needs: test
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    outputs:
      image-tag: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha,prefix=
            type=ref,event=branch

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  update-manifest:
    needs: build-and-push
    runs-on: ubuntu-latest
    steps:
      - name: Checkout manifest repo
        uses: actions/checkout@v4
        with:
          repository: myorg/k8s-manifests
          token: ${{ secrets.MANIFEST_REPO_TOKEN }}

      - name: Update image tag
        run: |
          cd apps/api-server/base
          kustomize edit set image \
            ghcr.io/myorg/api-server=ghcr.io/myorg/api-server:${{ needs.build-and-push.outputs.image-tag }}

      - name: Create PR
        uses: peter-evans/create-pull-request@v6
        with:
          token: ${{ secrets.MANIFEST_REPO_TOKEN }}
          commit-message: 'chore: update api-server image to ${{ needs.build-and-push.outputs.image-tag }}'
          title: 'deploy: api-server ${{ needs.build-and-push.outputs.image-tag }}'
          body: |
            Auto-generated deployment PR.
            - Source commit: ${{ github.sha }}
            - Image tag: ${{ needs.build-and-push.outputs.image-tag }}
          branch: deploy/api-server-${{ needs.build-and-push.outputs.image-tag }}
          base: main

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - hpa.yaml
commonLabels:
  app: api-server

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namePrefix: dev-
namespace: dev
patches:
  - path: patches/replicas.yaml
images:
  - name: ghcr.io/myorg/api-server
    newTag: latest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: api-server
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 200m
              memory: 256Mi

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namespace: production
patches:
  - path: patches/replicas.yaml
  - path: patches/resources.yaml
images:
  - name: ghcr.io/myorg/api-server
    newTag: v2.4.1 # Production uses explicit tags

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 5
  template:
    spec:
      containers:
        - name: api-server
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              cpu: '1'
              memory: 1Gi

helm-charts/
├── api-server/
│   ├── Chart.yaml
│   ├── templates/
│   ├── values.yaml            # defaults
│   ├── values-dev.yaml        # dev environment
│   ├── values-staging.yaml    # staging environment
│   └── values-prod.yaml       # production environment

# values-prod.yaml
replicaCount: 5
image:
  repository: ghcr.io/myorg/api-server
  tag: v2.4.1
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: '1'
    memory: 1Gi
autoscaling:
  enabled: true
  minReplicas: 5
  maxReplicas: 20
  targetCPUUtilization: 70
ingress:
  enabled: true
  hosts:
    - host: api.myservice.com
      paths:
        - path: /
          pathType: Prefix

# .github/CODEOWNERS
# Default owners
*                       @myorg/platform-team

# Infrastructure manifests
/apps/                  @myorg/sre-team
/argocd/                @myorg/sre-team

# Frontend
/apps/web-frontend/     @myorg/frontend-team

# Backend API
/apps/api-server/       @myorg/backend-team