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:

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:

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

Job Sequence:

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:

# Multi-stage build
FROM node:20-alpine AS builder
# ... build steps

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

Container Registry:

# 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):

# docker-compose.dev.yml
services:
  app:          # Next.js application
  mongodb:      # Database
  mongo-express: # Database UI
  loki:         # Logging
  grafana:      # Monitoring

---

🚀 Deployment Integration

Dokploy Integration:

# 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:

# Staging Environment
environment:
  name: staging
  url: https://staging.mozdit.hu

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

---

🔧 GitHub Configuration

Required Secrets:

# 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:

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

Branch Protection Rules:

# Recommended branch protection for main
required_status_checks:
  - test
  - docker-tests
  - build
required_reviews: 1
enforce_admins: true

---

📊 Monitoring & Reporting

GitHub Actions Status:

[![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:

## 🧪 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:

# 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:

# 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:

# 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

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

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

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:

# 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:

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
• Docker Setup
• Testing Guide
• Sync Status Analysis

---

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