GitOps + Git Workflow 총정리 — 브랜치 전략, PR 규칙, 배포 파이프라인

# 선언적 상태 정의 예시 - 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 ────●─────────────●──────●── (프로덕션)
          \           / \    /
release    \    ●────●   \  /
            \  /          \/
develop ─────●──●──●──●───●──●── (통합)
              \  \      /
feature        ●──●────●

main ────●──●──●──●──●── (항상 배포 가능)
          \    /  \  /
feature    ●──●    ●──●

main ────●──●──●──●──●──●──●── (모든 커밋이 배포 후보)
          \/ \/ \/
short     ●  ●  ●  (1일 이내 병합)

## 변경 사항

<!-- 무엇을 왜 변경했는지 간결하게 설명 -->

## 변경 유형

- [ ] 기능 추가 (feature)
- [ ] 버그 수정 (bugfix)
- [ ] 리팩토링 (refactor)
- [ ] 인프라/설정 변경 (infra)
- [ ] 문서 업데이트 (docs)

## 테스트

- [ ] 단위 테스트 추가/수정
- [ ] 통합 테스트 통과
- [ ] 로컬 환경에서 수동 검증

## 체크리스트

- [ ] 커밋 메시지가 Conventional Commits 형식을 따르는가?
- [ ] 불필요한 파일(로그, 임시 파일)이 포함되지 않았는가?
- [ ] 기존 API와 하위 호환되는가?
- [ ] 보안 민감 정보(시크릿, 키)가 포함되지 않았는가?

## 관련 이슈

Closes #

## 스크린샷 (UI 변경 시)

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

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

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

# 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 # Git에서 삭제된 리소스 자동 제거
      selfHeal: true # 드리프트 자동 교정
    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[개발자 Push] --> B[GitHub Actions CI]
    B --> C{테스트 통과?}
    C -->|Yes| D[컨테이너 이미지 빌드]
    C -->|No| E[실패 알림]
    D --> F[이미지 Push - GHCR]
    F --> G[매니페스트 저장소 PR 생성]
    G --> H[PR 자동 병합 / 수동 승인]
    H --> I[ArgoCD 감지]
    I --> J[Kubernetes 동기화]
    J --> K{Health Check}
    K -->|Healthy| L[배포 완료]
    K -->|Degraded| M[자동 롤백]

# .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: |
            자동 생성된 배포 PR입니다.
            - 소스 커밋: ${{ github.sha }}
            - 이미지 태그: ${{ 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 # 프로덕션은 명시적 태그 사용

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            # 기본값
│   ├── values-dev.yaml        # dev 환경
│   ├── values-staging.yaml    # staging 환경
│   └── values-prod.yaml       # production 환경

# 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
# 기본 소유자
*                       @myorg/platform-team

# 인프라 매니페스트
/apps/                  @myorg/sre-team
/argocd/                @myorg/sre-team

# 프론트엔드
/apps/web-frontend/     @myorg/frontend-team

# 백엔드 API
/apps/api-server/       @myorg/backend-team