peikarband/docs/WOODPECKER_CI_CD.md

# Woodpecker CI/CD Documentation

این مستند راهنمای کامل برای راه‌اندازی و استفاده از Woodpecker CI/CD pipeline برای پروژه Peikarband است.

## نمای کلی Pipeline

Pipeline ما شامل 8 مرحله اصلی است:

```
1. Code Quality & Linting
   ├── flake8 (Python linting)
   ├── black (Code formatting check)
   ├── isort (Import sorting)
   └── mypy (Type checking)

2. Security Scanning
   ├── bandit (Security vulnerability scan)
   └── safety (Dependency vulnerability check)

3. Testing
   └── pytest (Unit & Integration tests with coverage)

4. Helm Validation
   ├── helm lint
   └── helm template

5. Docker Build & Push
   └── Multi-platform build with caching

6. Deploy to Staging
   └── Auto-deploy on main/develop branches

7. Deploy to Production
   └── Manual trigger on version tags (v*)

8. Notifications
   └── Success/Failure notifications
```

## تنظیمات Secrets

برای اجرای کامل pipeline، باید secrets زیر را در Woodpecker تنظیم کنید:

### 1. Registry Secrets (الزامی برای Build)

```bash
HARBOR_USERNAME=admin
HARBOR_PASSWORD=your_harbor_password
```

**نحوه تنظیم در Woodpecker UI:**
1. رفتن به Repository Settings
2. کلیک روی "Secrets"
3. اضافه کردن secret جدید:
   - Name: `HARBOR_USERNAME`
   - Value: `admin`
   - Events: `push, tag`
4. تکرار برای `HARBOR_PASSWORD`

### 2. Kubernetes Secrets (الزامی برای Deployment)

#### Staging Environment

```bash
# Generate base64 encoded kubeconfig
cat ~/.kube/config-staging | base64 -w 0 > kubeconfig-staging-base64.txt

# Add to Woodpecker as secret
KUBECONFIG_STAGING=<content_of_kubeconfig-staging-base64.txt>
```

#### Production Environment

```bash
# Generate base64 encoded kubeconfig
cat ~/.kube/config-production | base64 -w 0 > kubeconfig-production-base64.txt

# Add to Woodpecker as secret
KUBECONFIG_PRODUCTION=<content_of_kubeconfig-production-base64.txt>
```

**⚠️ نکات امنیتی:**
- هرگز kubeconfig را در Git commit نکنید
- از RBAC برای محدود کردن دسترسی kubeconfig استفاده کنید
- به‌طور منظم kubeconfig را rotate کنید
- فقط namespace های staging و production دسترسی داشته باشند

### 3. Optional: ArgoCD Integration

اگر می‌خواهید از ArgoCD برای deployment استفاده کنید:

```bash
ARGOCD_SERVER=argocd.peikarband.ir
ARGOCD_AUTH_TOKEN=your_argocd_token
```

## Branch Strategy

Pipeline بر اساس branch و event متفاوت رفتار می‌کند:

### Pull Request (PR)

```yaml
Stages: Lint + Test + Security + Helm Lint
Skip: Build, Deploy
Purpose: Code quality validation
```

**مثال:**

```bash
# Create PR
git checkout -b feature/new-feature
git push origin feature/new-feature
# Open PR in GitLab/GitHub -> Pipeline runs automatically
```

### Main Branch (Push)

```yaml
Stages: All stages
Deploy: Staging (automatic)
Tags: latest, main-<sha>, <sha>
```

**مثال:**

```bash
git checkout main
git pull origin main
git merge feature/new-feature
git push origin main
# -> Automatic: Test -> Build -> Deploy to Staging
```

### Develop Branch (Push)

```yaml
Stages: All stages
Deploy: Staging (automatic)
Tags: develop, develop-<sha>, <sha>
```

**مثال:**

```bash
git checkout develop
git push origin develop
# -> Automatic: Test -> Build -> Deploy to Staging
```

### Version Tags (Production)

```yaml
Stages: All stages
Deploy: Production (automatic)
Tags: latest, v1.2.3, <sha>
```

**مثال:**

```bash
# Create and push version tag
git checkout main
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
# -> Automatic: Test -> Build -> Deploy to Production
```

## Pipeline Triggers

### Automatic Triggers

1. **Push به branch:**
   ```bash
   git push origin main        # Trigger full pipeline + deploy staging
   git push origin develop     # Trigger full pipeline + deploy staging
   git push origin feature/*   # No trigger (manual only)
   ```

2. **Tag push:**
   ```bash
   git push origin v1.0.0      # Trigger full pipeline + deploy production
   ```

3. **Pull Request:**
   ```bash
   # Any PR -> Triggers lint/test/security only
   ```

### Manual Triggers

در Woodpecker UI:
1. رفتن به Repository
2. کلیک روی "Pipelines"
3. کلیک روی "New Pipeline"
4. انتخاب branch/commit
5. کلیک روی "Start"

## Docker Image Tagging

Pipeline به‌طور خودکار images را با تگ‌های مختلف می‌سازد:

### Main Branch

```
hub.peikarband.ir/peikarband/landing:latest
hub.peikarband.ir/peikarband/landing:main
hub.peikarband.ir/peikarband/landing:a1b2c3d4  # commit SHA
```

### Develop Branch

```
hub.peikarband.ir/peikarband/landing:develop
hub.peikarband.ir/peikarband/landing:develop-a1b2c3d4
hub.peikarband.ir/peikarband/landing:a1b2c3d4
```

### Version Tags

```
hub.peikarband.ir/peikarband/landing:latest
hub.peikarband.ir/peikarband/landing:v1.0.0
hub.peikarband.ir/peikarband/landing:a1b2c3d4
```

## Deployment Process

### Staging Deployment

**Trigger:** هر push به `main` یا `develop`

**فرایند:**
1. Tests pass
2. Build Docker image
3. Push to registry with tag `<branch>-<sha>`
4. Helm upgrade to `staging` namespace
5. Wait for rollout (timeout: 5 minutes)
6. Show pod status

**Rollback:**

```bash
# List helm releases
helm list -n staging

# Rollback to previous version
helm rollback peikarband-staging -n staging

# Or rollback to specific revision
helm rollback peikarband-staging 5 -n staging
```

### Production Deployment

**Trigger:** Push tag با pattern `v*` (مثل `v1.0.0`)

**فرایند:**
1. Tests pass
2. Build Docker image
3. Push to registry with tags `latest`, `v1.0.0`, `<sha>`
4. Helm upgrade to `production` namespace with production values
5. Wait for rollout (timeout: 10 minutes)
6. Verify deployment
7. Show pod status

**Rollback:**

```bash
# Check current status
kubectl get pods -n production

# Rollback via Helm
helm rollback peikarband -n production

# Or rollback via kubectl
kubectl rollout undo deployment/peikarband -n production

# Check rollout status
kubectl rollout status deployment/peikarband -n production
```

## Monitoring Pipeline

### Via Woodpecker UI

1. رفتن به: `https://woodpecker.peikarband.ir` (یا آدرس Woodpecker شما)
2. انتخاب repository
3. مشاهده لیست pipeline runs
4. کلیک روی یک run برای مشاهده جزئیات

### Via CLI

```bash
# Install Woodpecker CLI
curl -L https://github.com/woodpecker-ci/woodpecker/releases/latest/download/woodpecker-cli_linux_amd64.tar.gz | tar xz
sudo mv woodpecker-cli /usr/local/bin/

# Configure
export WOODPECKER_SERVER=https://woodpecker.peikarband.ir
export WOODPECKER_TOKEN=your_token

# List pipelines
woodpecker pipeline ls

# Show pipeline info
woodpecker pipeline info <number>

# Show logs
woodpecker pipeline logs <number>

# Approve waiting pipeline
woodpecker pipeline approve <number>
```

## Troubleshooting

### Pipeline Fails at Lint Stage

**مشکل:** کد formatting یا linting مشکل دارد

**راه‌حل:**

```bash
cd peikarband

# Fix formatting
black src/
isort src/

# Check linting
flake8 src/

# Commit fixes
git add .
git commit -m "fix: code formatting and linting"
git push
```

### Pipeline Fails at Test Stage

**مشکل:** تست‌ها fail می‌شوند

**راه‌حل:**

```bash
cd peikarband

# Run tests locally
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src

# Fix tests and re-run
git add .
git commit -m "fix: failing tests"
git push
```

### Pipeline Fails at Docker Build

**مشکل:** Docker build error

**راه‌حل:**

```bash
# Test build locally
docker build -f docker/Dockerfile -t test:latest .

# Check Dockerfile syntax
docker build --check -f docker/Dockerfile .

# Check build context
ls -la peikarband/

# Common issues:
# 1. Missing files in context
# 2. COPY path wrong
# 3. Build args missing
```

### Pipeline Fails at Deployment

**مشکل:** Helm deployment fail

**راه‌حل:**

```bash
# Test Helm locally
helm lint helm/peikarband
helm template peikarband helm/peikarband -f helm/peikarband/values-staging.yaml

# Check kubectl access
kubectl get pods -n staging

# Check secrets
kubectl get secrets -n staging

# Check image pull
kubectl describe pod <pod-name> -n staging
```

### Secret Not Found Error

**مشکل:** `Secret not found: HARBOR_USERNAME`

**راه‌حل:**
1. رفتن به Woodpecker UI > Repository > Settings > Secrets
2. بررسی که secret با نام درست اضافه شده
3. بررسی که secret برای event درست (push, tag, etc.) فعال است
4. بررسی که secret برای branch درست در دسترس است

### Kubeconfig Invalid

**مشکل:** `Unable to connect to the server`

**راه‌حل:**

```bash
# Test kubeconfig locally
export KUBECONFIG=/path/to/your/kubeconfig
kubectl get pods

# Re-encode kubeconfig
cat ~/.kube/config | base64 -w 0

# Update secret in Woodpecker
# Copy new base64 string to KUBECONFIG_STAGING or KUBECONFIG_PRODUCTION
```

## Performance Optimization

### Build Cache

Pipeline از Docker layer caching استفاده می‌کند:

```yaml
cache_from: type=registry,ref=hub.peikarband.ir/peikarband/landing:buildcache
cache_to: type=inline
```

**بهینه‌سازی بیشتر:**

1. **Dependencies Caching:** requirements.txt را قبل از کد اصلی COPY کنید
2. **Multi-stage Build:** از multi-stage builds استفاده کنید
3. **Parallel Stages:** مراحل مستقل را parallel اجرا کنید

### Pipeline Duration

زمان تقریبی هر stage:

```
Lint stages:     ~1-2 minutes
Security scan:   ~2-3 minutes
Tests:           ~3-5 minutes
Helm validation: ~30 seconds
Docker build:    ~5-10 minutes (first time), ~2-3 minutes (cached)
Deployment:      ~2-5 minutes
Total:           ~15-30 minutes (full pipeline)
```

## Best Practices

### 1. Commit Messages

از conventional commits استفاده کنید:

```bash
feat: add new feature
fix: bug fix
docs: documentation changes
style: formatting changes
refactor: code refactoring
test: test changes
chore: build/CI changes
```

### 2. Version Tagging

```bash
# Semantic versioning
v1.0.0  # Major.Minor.Patch
v1.0.1  # Patch release
v1.1.0  # Minor release
v2.0.0  # Major release

# Pre-release versions
v1.0.0-rc.1  # Release candidate
v1.0.0-beta.1  # Beta release
v1.0.0-alpha.1  # Alpha release
```

### 3. Feature Branches

```bash
# Create feature branch
git checkout -b feature/user-authentication
# ... make changes ...
git add .
git commit -m "feat: add user authentication"
git push origin feature/user-authentication

# Create PR
# After approval, merge to develop
git checkout develop
git merge feature/user-authentication
git push origin develop
# -> Triggers pipeline + deploy to staging

# After testing in staging, merge to main
git checkout main
git merge develop
git push origin main
# -> Triggers pipeline + deploy to staging

# Create production release
git tag -a v1.1.0 -m "Release v1.1.0: Add user authentication"
git push origin v1.1.0
# -> Triggers pipeline + deploy to production
```

### 4. Hotfix Process

```bash
# Create hotfix branch from main
git checkout -b hotfix/critical-bug main

# Fix the bug
git add .
git commit -m "fix: critical security vulnerability"

# Merge to main
git checkout main
git merge hotfix/critical-bug

# Tag immediately
git tag -a v1.0.1 -m "Hotfix v1.0.1: Security patch"
git push origin main v1.0.1
# -> Triggers pipeline + deploy to production

# Merge back to develop
git checkout develop
git merge hotfix/critical-bug
git push origin develop
```

## Environment Variables

### Available in Pipeline

```bash
CI=woodpecker                           # Always set
CI_REPO=username/peikarband             # Repository name
CI_REPO_LINK=https://git.../peikarband  # Repository URL
CI_COMMIT_SHA=a1b2c3d4e5f6...           # Full commit hash
CI_COMMIT_BRANCH=main                   # Branch name
CI_COMMIT_TAG=v1.0.0                    # Tag (if triggered by tag)
CI_COMMIT_MESSAGE=feat: new feature     # Commit message
CI_PIPELINE_CREATED=2024-01-01T...      # Pipeline creation time
CI_PIPELINE_NUMBER=123                  # Pipeline number
```

### Usage Example

```bash
# In pipeline step
echo "Building commit ${CI_COMMIT_SHA:0:8} from branch ${CI_COMMIT_BRANCH}"
echo "Image tag: hub.peikarband.ir/peikarband/landing:${CI_COMMIT_SHA:0:8}"
```

## Support & Contact

برای مشکلات و سوالات:
- **Documentation:** این فایل
- **Issues:** GitLab/GitHub Issues
- **Team Contact:** dev@peikarband.ir

## مراجع

- [Woodpecker CI Documentation](https://woodpecker-ci.org/docs/intro)
- [Docker Build Best Practices](https://docs.docker.com/develop/dev-best-practices/)
- [Helm Documentation](https://helm.sh/docs/)
- [Kubernetes Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)