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)

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

# 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

# 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 استفاده کنید:

ARGOCD_SERVER=argocd.peikarband.ir
ARGOCD_AUTH_TOKEN=your_argocd_token

Branch Strategy

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

Pull Request (PR)

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

مثال:

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

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

مثال:

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)

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

مثال:

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

Version Tags (Production)

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

مثال:

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

   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:

   git push origin v1.0.0      # Trigger full pipeline + deploy production
   

3. Pull Request:

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

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

# 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

# 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 مشکل دارد

راه‌حل:

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 می‌شوند

راه‌حل:

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

راه‌حل:

# 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

راه‌حل:

# 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

راه‌حل:

# 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 استفاده می‌کند:

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 استفاده کنید:

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

# 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

# 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

# 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

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

# 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
• Docker Build Best Practices
• Helm Documentation
• Kubernetes Deployments