# GMP Platform — Panduan CI/CD GitHub untuk Management Project Tim

Panduan ini menjadi standar operasional tim untuk mengelola alur kerja development, review, release, dan deployment di GitHub menggunakan GitHub Actions.

---

## Daftar Isi

1. [Tujuan & Ruang Lingkup](#1-tujuan--ruang-lingkup)
2. [Prinsip Team Management](#2-prinsip-team-management)
3. [Branching Strategy](#3-branching-strategy)
4. [Standar Issue, Pull Request, dan Review](#4-standar-issue-pull-request-dan-review)
5. [Struktur Environment Deployment](#5-struktur-environment-deployment)
6. [Arsitektur CI/CD yang Direkomendasikan](#6-arsitektur-cicd-yang-direkomendasikan)
7. [Contoh Workflow GitHub Actions](#7-contoh-workflow-github-actions)
8. [Secrets & Keamanan](#8-secrets--keamanan)
9. [Release Management](#9-release-management)
10. [Incident & Rollback](#10-incident--rollback)
11. [Checklist Implementasi Awal](#11-checklist-implementasi-awal)

---

## 1. Tujuan & Ruang Lingkup

Tujuan utama:
- Menstandarkan proses kerja lintas tim (backend, frontend, QA, DevOps).
- Mengurangi human error saat integrasi dan deployment.
- Memastikan setiap perubahan tervalidasi otomatis sebelum masuk branch utama.

Ruang lingkup panduan ini mencakup:
- Repository governance di GitHub.
- CI untuk quality gate (lint, test, build).
- CD untuk staging dan production.
- Proses release dan rollback.

---

## 2. Prinsip Team Management

1. **Single source of truth**: semua task berasal dari issue/ticket.
2. **Traceable change**: setiap PR wajib terkait issue.
3. **Small batch delivery**: PR kecil, fokus, mudah direview.
4. **Quality gate wajib lulus**: tidak boleh merge jika check gagal.
5. **Automate first**: validasi berulang harus otomatis di pipeline.

---

## 3. Branching Strategy

Gunakan model berikut:

- `main` → branch production (protected, hanya via PR).
- `develop` → branch integrasi untuk staging.
- `feature/<scope>-<short-title>` → pengembangan fitur.
- `fix/<scope>-<short-title>` → bug fix non-kritis.
- `hotfix/<scope>-<short-title>` → perbaikan darurat production.

Contoh:
- `feature/finance-invoice-export`
- `fix/ecustomer-filter-status`
- `hotfix/auth-sso-token-refresh`

Aturan merge:
- `feature/*` dan `fix/*` merge ke `develop`.
- release kandidat dari `develop` ke `main`.
- `hotfix/*` merge ke `main`, lalu back-merge ke `develop`.

---

## 4. Standar Issue, Pull Request, dan Review

### 4.1 Issue

Minimum isi issue:
- Problem statement
- Acceptance criteria
- Scope app/module (contoh: `apps/finance`, `apps/ecustomer`)
- Label prioritas (`P0`, `P1`, `P2`)

### 4.2 Pull Request

Wajib mencantumkan:
- Link issue (`Closes #123`)
- Ringkasan perubahan
- Risiko dan dampak
- Bukti test (screenshot/log/test output)

### 4.3 Code Review Policy

- Minimal **1 approver** untuk perubahan minor.
- Minimal **2 approver** untuk perubahan high-impact (auth, payment, schema).
- Wajib lulus semua status check sebelum merge.
- Gunakan **Squash merge** agar history bersih dan mudah ditelusuri.

---

## 5. Struktur Environment Deployment

Rekomendasi environment:

- **Development**: lokal/dev server tim.
- **Staging**: mirror production untuk UAT/QA.
- **Production**: environment live.

Mapping branch:
- `develop` → deploy otomatis ke staging.
- `main` → deploy otomatis ke production (dengan approval environment).

Di GitHub, aktifkan `Environments`:
- `staging`
- `production` (required reviewers, wait timer opsional)

---

## 6. Arsitektur CI/CD yang Direkomendasikan

Pisahkan workflow agar mudah dikelola:

1. **CI Pull Request** (`ci-pr.yml`)
   - Trigger: `pull_request` ke `develop`/`main`
   - Tugas: lint, test, build

2. **CD Staging** (`cd-staging.yml`)
   - Trigger: `push` ke `develop`
   - Tugas: deploy staging, smoke test

3. **CD Production** (`cd-production.yml`)
   - Trigger: `push` ke `main` atau manual `workflow_dispatch`
   - Tugas: deploy production, post-deploy verification

4. **Maintenance** (opsional)
   - Dependency update, security scan, cleanup artifacts

---

## 7. Contoh Workflow GitHub Actions

Buat folder `.github/workflows/` lalu tambahkan file berikut.

### 7.1 `ci-pr.yml`

```yaml
name: CI Pull Request

on:
  pull_request:
    branches: [develop, main]

concurrency:
  group: ci-pr-${{ github.ref }}
  cancel-in-progress: true

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

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

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          extensions: mbstring, intl, pdo_mysql
          tools: composer:v2

      - name: Install root dependencies
        run: npm ci

      - name: Lint workspace
        run: npm run lint --if-present

      - name: Build workspace
        run: npm run build --if-present

      - name: Test workspace
        run: npm run test --if-present
```

### 7.2 `cd-staging.yml`

```yaml
name: CD Staging

on:
  push:
    branches: [develop]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.STAGING_HOST }}
          username: ${{ secrets.STAGING_USER }}
          key: ${{ secrets.STAGING_SSH_KEY }}
          script: |
            cd /var/www/gmp_platform
            git pull origin develop
            npm ci
            npm run build
            php artisan migrate --force
            php artisan optimize:clear
```

### 7.3 `cd-production.yml`

```yaml
name: CD Production

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy-production:
    runs-on: ubuntu-latest
    environment: production

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.PROD_HOST }}
          username: ${{ secrets.PROD_USER }}
          key: ${{ secrets.PROD_SSH_KEY }}
          script: |
            cd /var/www/gmp_platform
            git pull origin main
            npm ci
            npm run build
            php artisan migrate --force
            php artisan optimize:clear
```

Catatan:
- Untuk monorepo besar, bisa ditingkatkan dengan path filter per app (`apps/auth/**`, `apps/finance/**`, dst).
- Jika deploy berbasis container, ganti langkah deploy dengan build/push image + rollout orchestrator.

---

## 8. Secrets & Keamanan

Simpan credential hanya di GitHub Secrets:
- `STAGING_HOST`, `STAGING_USER`, `STAGING_SSH_KEY`
- `PROD_HOST`, `PROD_USER`, `PROD_SSH_KEY`
- `APP_KEY`, token service lain jika diperlukan

Best practices:
- Jangan commit `.env` ke repo.
- Rotasi key secara berkala.
- Gunakan akun deploy khusus (least privilege).
- Aktifkan branch protection + required status checks.

---

## 9. Release Management

Rekomendasi cadence:
- Release rutin mingguan atau dua mingguan.
- Gunakan tag semantik: `vMAJOR.MINOR.PATCH`.
- Buat release note dari merged PR.

Template ringkas release note:
- Added
- Changed
- Fixed
- Breaking Changes (jika ada)

---

## 10. Incident & Rollback

Jika deployment bermasalah:

1. Freeze merge sementara ke `main`.
2. Lakukan rollback ke tag stabil terakhir.
3. Jalankan smoke test kritikal.
4. Buat postmortem (root cause + action item).

Contoh rollback (konsep umum):

```bash
git checkout v1.4.2
# redeploy revision ini ke server production
```

---

## 11. Checklist Implementasi Awal

- [ ] Buat branch protection untuk `main` dan `develop`
- [ ] Wajibkan status checks dari `ci-pr.yml`
- [ ] Aktifkan CODEOWNERS untuk ownership review
- [ ] Tambahkan PR template dan issue template
- [ ] Buat environment `staging` dan `production`
- [ ] Isi seluruh secrets deployment di GitHub
- [ ] Aktifkan notifikasi gagal pipeline ke channel tim (Slack/Teams)
- [ ] Simulasi deployment + rollback sebelum go-live

---

Dokumen ini bisa dijadikan baseline. Setelah 2–4 sprint, evaluasi metrik utama (lead time, change failure rate, MTTR) lalu iterasi pipeline sesuai kebutuhan tim.