websitedev/GITHUB-CICD-GUIDE.md

# GitHub CI/CD Guide - Code & Deployment

## 🎯 **Cél: GitHub-specifikus CI/CD Pipeline**

Ez a dokumentum a **GitHub Actions** rendszerét írja le, amely **csak** a CI/CD és deployment-re fókuszál.

---

## 🚀 **GitHub CI/CD Architektúra**

### **Pipeline Folyamat:**
```mermaid
graph TD
    A[Code Push] --> B[GitHub Actions]
    B --> C[Run Tests]
    B --> D[Build Docker Image]
    B --> E[Push to Registry]
    B --> F[Deploy to Dokploy]
    
    G[PR Creation] --> H[Test Validation]
    H --> I[Staging Deploy]
    
    J[Manual Trigger] --> B
```

### **Mit kezel a GitHub CI/CD:**
- ✅ **Source Code** versioning és tracking
- ✅ **Test Execution** (unit, integration, e2e)
- ✅ **Docker Image** build és registry push
- ✅ **Deployment** staging és production környezetekre
- ✅ **PR Validation** és code review support
- ✅ **Build Artifacts** és reporting

---

## 🔄 **GitHub Actions Workflows**

### **1. Main CI/CD Pipeline (`.github/workflows/ci.yml`)**

#### **Trigger Events:**
```yaml
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
```

#### **Job Sequence:**
```mermaid
graph LR
    A[Test Phase] --> B[Docker Tests]
    B --> C[Build Phase]
    C --> D[Test Summary]
    D --> E[Deploy Staging]
    D --> F[Deploy Production]
```

#### **Jobs Detail:**

##### **🧪 Test Phase**
- **Unit Tests**: Component és API tesztek
- **Browser Integration**: jsdom + mocked APIs
- **Test Artifacts**: JSON results export

##### **🐳 Docker Integration Tests**
- **Docker Services**: Next.js + MongoDB + monitoring
- **Integration Tests**: Real HTTP calls
- **E2E Tests**: Complete user workflows

##### **🏗️ Build Phase**
- **Docker Image**: Multi-stage production build
- **Registry Push**: GitHub Container Registry
- **Image Tagging**: Branch és commit alapján

##### **📊 Test Summary**
- **PR Comments**: Test results summary
- **Build Status**: Success/failure reporting
- **Artifact Upload**: Test results és reports

##### **🚀 Deployment**
- **Staging**: `develop` branch → Dokploy staging
- **Production**: `main` branch → Dokploy production

---

## 🐳 **Docker Integration**

### **Docker Image Build:**
```dockerfile
# Multi-stage build
FROM node:20-alpine AS builder
# ... build steps

FROM node:20-alpine AS runner
# ... production setup
```

### **Container Registry:**
```yaml
# GitHub Container Registry
registry: ghcr.io
image: ghcr.io/your-username/websitedev
tags: |
  type=ref,event=branch
  type=sha,prefix={{branch}}-
  type=raw,value=latest,enable={{is_default_branch}}
```

### **Docker Services (Testing):**
```yaml
# docker-compose.dev.yml
services:
  app:          # Next.js application
  mongodb:      # Database
  mongo-express: # Database UI
  loki:         # Logging
  grafana:      # Monitoring
```

---

## 🚀 **Deployment Integration**

### **Dokploy Integration:**
```yaml
# Staging Deployment
deploy-staging:
  if: github.ref == 'refs/heads/develop'
  environment: staging
  steps:
    - name: Deploy to Dokploy Staging
      run: |
        curl -X POST "${{ secrets.DOKPLOY_STAGING_WEBHOOK }}" \
             -H "Authorization: Bearer ${{ secrets.DOKPLOY_TOKEN }}" \
             -d '{"image": "${{ needs.build.outputs.image-tag }}"}'

# Production Deployment  
deploy-production:
  if: github.ref == 'refs/heads/main'
  environment: production
  steps:
    - name: Deploy to Dokploy Production
      run: |
        curl -X POST "${{ secrets.DOKPLOY_PROD_WEBHOOK }}" \
             -H "Authorization: Bearer ${{ secrets.DOKPLOY_TOKEN }}" \
             -d '{"image": "${{ needs.build.outputs.image-tag }}"}'
```

### **Environment Configuration:**
```yaml
# Staging Environment
environment:
  name: staging
  url: https://staging.mozdit.hu

# Production Environment
environment:
  name: production
  url: https://mozdit.hu
```

---

## 🔧 **GitHub Configuration**

### **Required Secrets:**
```bash
# GitHub Repository Secrets
DOKPLOY_STAGING_WEBHOOK=https://staging.webhook.url
DOKPLOY_PROD_WEBHOOK=https://prod.webhook.url
DOKPLOY_TOKEN=your_dokploy_token

# Optional (for advanced features)
GITHUB_TOKEN=auto_provided
```

### **Environment Variables:**
```yaml
env:
  NODE_VERSION: '20'
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
```

### **Branch Protection Rules:**
```yaml
# Recommended branch protection for main
required_status_checks:
  - test
  - docker-tests
  - build
required_reviews: 1
enforce_admins: true
```

---

## 📊 **Monitoring & Reporting**

### **GitHub Actions Status:**
```markdown
[![CI/CD Pipeline](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)]
[![Docker](https://img.shields.io/badge/Docker-Ready-blue)]
[![Deployment](https://img.shields.io/badge/Deployment-Active-success)]
```

### **PR Comments:**
```markdown
## 🧪 Test Results Summary

### ✅ Unit Tests
- All unit tests passed
- Component tests: ✅
- API tests: ✅

### 🐳 Integration Tests
- Docker services tested
- API endpoints: ✅
- Database connectivity: ✅

### 📊 Build Status
- Tests: ✅ All passing
- Docker build: ✅ Ready
- Deployment: ✅ Ready
```

### **Build Artifacts:**
- **Test Results**: `unit-results.json`, `integration-results.json`
- **Docker Images**: `ghcr.io/user/repo:tag`
- **Build Logs**: GitHub Actions logs
- **Deployment Status**: Dokploy integration

---

## 🛠️ **Local Development Integration**

### **Pre-commit Hooks:**
```bash
# Install pre-commit hooks
npm install --save-dev husky lint-staged

# package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,ts,tsx}": ["eslint --fix", "git add"]
  }
}
```

### **Local Testing:**
```bash
# Run same tests as CI
npm run test:all

# Test Docker build locally
npm run docker:build

# Test deployment locally
npm run docker:run
```

### **Git Workflow:**
```bash
# Feature development
git checkout -b feature/new-feature
# ... development
git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

# Create PR
gh pr create --title "Add new feature" --body "Description"

# After review and merge
git checkout main
git pull origin main
# Automatic deployment triggers
```

---

## 🔍 **Troubleshooting**

### **Gyakori Problémák:**

#### **1. Docker Build Fails**
```bash
Error: Docker build failed
```
**Megoldás:**
- Ellenőrizd a `Dockerfile` syntax-át
- Ellenőrizd a `package.json` dependencies-ét
- Ellenőrizd a build context-et

#### **2. Test Failures**
```bash
Error: Tests failed in CI
```
**Megoldás:**
- Futtasd a teszteket helyileg: `npm run test:all`
- Ellenőrizd a test environment változókat
- Ellenőrizd a Docker services állapotát

#### **3. Deployment Fails**
```bash
Error: Dokploy deployment failed
```
**Megoldás:**
- Ellenőrizd a `DOKPLOY_*` secrets-eket
- Ellenőrizd a webhook URL-eket
- Ellenőrizd a Dokploy service állapotát

### **Debug Commands:**
```bash
# Local Docker testing
docker-compose -f docker-compose.dev.yml up -d
docker-compose -f docker-compose.dev.yml logs -f

# GitHub Actions debugging
gh run list --workflow=ci.yml
gh run view <run-id> --log

# Docker image testing
docker run -p 3000:3000 ghcr.io/user/repo:latest
```

---

## 📋 **Best Practices**

### **1. Branch Strategy:**
- `main` → Production deployment
- `develop` → Staging deployment
- `feature/*` → Development branches
- `hotfix/*` → Critical fixes

### **2. Commit Messages:**
```bash
feat: add new feature
fix: resolve bug
docs: update documentation
test: add tests
refactor: code refactoring
```

### **3. PR Guidelines:**
- Minden PR-nek kell test coverage
- Minden PR-nek kell review
- Breaking changes dokumentálása
- Changelog frissítése

### **4. Deployment Strategy:**
- Staging deployment minden `develop` push után
- Production deployment csak `main` merge után
- Rollback strategy kész
- Health checks minden deployment után

---

## 🔗 **Kapcsolódó Dokumentumok**

- [Linear Sync Guide](./LINEAR-SYNC-GUIDE.md)
- [Docker Setup](./DOCKER.md)
- [Testing Guide](./proto/TESTING.md)
- [Sync Status Analysis](./SYNC-STATUS-ANALYSIS.md)

---

**Utolsó frissítés:** 2025-09-05  
**Státusz:** GitHub CI/CD szétválasztva Linear sync-től  
**Következő lépés:** Dokploy konfiguráció és secrets beállítása