Vapora/provisioning/.github/SETUP.md

# GitHub Actions Setup Guide

Quick setup guide to enable GitHub Actions CI/CD for VAPORA provisioning.

## 5-Minute Setup

### Step 1: Enable GitHub Actions

1. Go to repository Settings
2. Navigate to "Actions" → "General"
3. Select "Allow all actions and reusable workflows"
4. Set "Workflow permissions" to "Read and write permissions"
5. Save changes

### Step 2: Add Required Secrets

Go to Settings → Secrets and variables → Actions → New repository secret

#### Kubernetes Kubeconfigs (Required for K8s deployments)

```bash
# Get kubeconfig and encode as base64
cat ~/.kube/config | base64

# Create these secrets:
# KUBE_CONFIG_STAGING (for staging cluster)
# KUBE_CONFIG_PRODUCTION (for production cluster)
```

**For CI/Test Cluster** (Optional):
- Secret name: `KUBE_CONFIG_CI`
- Value: Base64-encoded kubeconfig

#### Slack Webhooks (Optional, for notifications)

```
SLACK_WEBHOOK               # For general notifications
SLACK_WEBHOOK_ALERTS        # For critical alerts
```

[How to create Slack webhooks](https://api.slack.com/apps)

#### Docker Registry (Optional, for image pushes)

```
DOCKER_USERNAME             # Docker Hub username
DOCKER_PASSWORD             # Docker Hub access token
```

### Step 3: Verify Setup

1. Go to Actions tab
2. You should see 5 workflows listed:
   - ✓ Validate & Build Artifacts
   - ✓ Deploy to Docker
   - ✓ Deploy to Kubernetes
   - ✓ Health Check & Monitoring
   - ✓ Rollback Deployment

3. Click on "Validate & Build Artifacts"
4. Click "Run workflow" → "Run workflow"
5. Wait for completion (should take ~5 minutes)

### Step 4: Download Artifacts

1. Go to the completed workflow run
2. Scroll down to "Artifacts"
3. Download `deployment-artifacts`
4. Extract and review generated files

---

## Detailed Setup

### Configure Kubernetes Access

#### 1. Staging Cluster

```bash
# Get kubeconfig context for staging
kubectl config view --minify --flatten --context=staging-context > staging-kubeconfig.yaml

# Encode for GitHub
cat staging-kubeconfig.yaml | base64

# Create secret KUBE_CONFIG_STAGING with the base64 output
```

#### 2. Production Cluster

```bash
# Get kubeconfig context for production
kubectl config view --minify --flatten --context=prod-context > prod-kubeconfig.yaml

# Encode for GitHub
cat prod-kubeconfig.yaml | base64

# Create secret KUBE_CONFIG_PRODUCTION with the base64 output
```

#### 3. Verify Kubeconfig

```bash
# Test decoding
echo $KUBE_CONFIG_STAGING | base64 -d | kubectl cluster-info

# Should output cluster information if valid
```

### Configure Slack Integration

#### 1. Create Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click "Create New App" → "From scratch"
3. App Name: `vapora-deployments`
4. Workspace: Select your workspace
5. Click "Create App"

#### 2. Enable Incoming Webhooks

1. Click "Incoming Webhooks" from left menu
2. Toggle "Activate Incoming Webhooks" to ON
3. Click "Add New Webhook to Workspace"
4. Select channel: `#deployments`
5. Click "Allow"
6. Copy the webhook URL

#### 3. Create Alert Webhook

1. Back on Incoming Webhooks page
2. Click "Add New Webhook to Workspace"
3. Select channel: `#alerts`
4. Click "Allow"
5. Copy the webhook URL

#### 4. Store Webhooks in GitHub

Create these secrets:
- `SLACK_WEBHOOK` = General notifications webhook
- `SLACK_WEBHOOK_ALERTS` = Critical alerts webhook

### Configure Docker Registry (Optional)

#### 1. Generate Docker Access Token

1. Go to [hub.docker.com](https://hub.docker.com)
2. Click your profile → Account settings
3. Navigate to "Security" → "Access Tokens"
4. Click "New Access Token"
5. Name: `github-actions`
6. Copy the token

#### 2. Store in GitHub

Create these secrets:
- `DOCKER_USERNAME` = Your Docker Hub username
- `DOCKER_PASSWORD` = The access token

---

## Branch Protection Rules (Recommended)

### Protect Main Branch

1. Go to Settings → Branches
2. Click "Add rule"
3. Branch name pattern: `main`
4. Enable:
   - ✓ Require a pull request before merging
   - ✓ Require status checks to pass
   - ✓ Require branches to be up to date
   - ✓ Include administrators
5. Save changes

### Protect Develop Branch

1. Add new rule
2. Branch name pattern: `develop`
3. Enable:
   - ✓ Require a pull request before merging
   - ✓ Require status checks to pass
4. Save changes

---

## First Deployment Walkthrough

### 1. Create Feature Branch

```bash
git checkout -b feature/test-deployment
```

### 2. Make a Small Change

```bash
# Edit a configuration file
echo "# Test" >> provisioning/schemas/platform/README.md

git add provisioning/
git commit -m "test: trigger validation workflow"
git push origin feature/test-deployment
```

### 3. Watch Validation

1. Go to Actions tab
2. See "Validate & Build Artifacts" running
3. Wait for completion (~5 minutes)
4. Verify no errors

### 4. Download Artifacts

1. Click the completed workflow
2. Scroll to Artifacts
3. Download `deployment-artifacts`
4. Extract and verify contents

### 5. Test Docker Deployment

1. Extract artifacts
2. Go to Actions → Deploy to Docker
3. Click "Run workflow"
4. Inputs:
   - mode: `multiuser`
   - dry_run: `true`
   - environment: `development`
5. Click "Run workflow"
6. Monitor the run
7. Verify Docker Compose validates

### 6. Test Kubernetes Deployment (Dry-run)

1. Go to Actions → Deploy to Kubernetes
2. Click "Run workflow"
3. Inputs:
   - mode: `multiuser`
   - dry_run: `true`
   - environment: `staging`
4. Click "Run workflow"
5. Monitor execution
6. Verify manifests are valid

### 7. Create Pull Request

```bash
# Push and create PR
git push origin feature/test-deployment

# Or go to GitHub and create PR from UI
```

---

## Monitoring Your Deployments

### Via GitHub Actions UI

1. Go to **Actions** tab
2. Select workflow to view
3. Click specific run to see details
4. Scroll to see jobs and logs
5. Download artifacts for review

### Via Slack

Messages will appear in:
- `#deployments` - General notifications
- `#alerts` - Critical failures only

### Via CLI

```bash
# View logs for a specific deployment
kubectl logs -f deployment/vapora-backend -n vapora

# Check deployment status
kubectl get deployments -n vapora

# View events
kubectl get events -n vapora --sort-by='.lastTimestamp'
```

---

## Common Tasks

### Validate a Configuration Change

1. Make changes to provisioning/schemas/
2. Push to feature branch
3. Validate & Build runs automatically
4. Review logs and artifacts
5. No manual steps needed

### Deploy to Staging

1. Create PR with provisioning changes
2. Get code review
3. Merge to develop
4. Go to Actions → Deploy to Kubernetes
5. Run workflow with:
   - mode: your choice
   - environment: staging
   - dry_run: true (first)
6. Review dry-run output
7. Run again with dry_run: false

### Deploy to Production

1. Create PR to main (from develop)
2. Get required reviews
3. All status checks must pass
4. Merge to main
5. Run Validate & Build (should pass)
6. Go to Actions → Deploy to Kubernetes
7. Run workflow with:
   - mode: your choice
   - environment: production
   - dry_run: true
8. Carefully review all changes
9. Run again with dry_run: false
10. Monitor health checks

### Check System Health

1. Go to Actions → Health Check & Monitoring
2. Click "Run workflow"
3. Select target and count
4. Monitor execution
5. Review health report in artifacts

### Rollback a Deployment

1. Go to Actions → Rollback Deployment
2. Click "Run workflow"
3. Select:
   - target: kubernetes or docker
   - environment: staging or production
   - deployment: all or specific service
   - revision: 0 (for previous) or number
4. Click "Run workflow"
5. Monitor execution
6. Review rollback report

---

## Troubleshooting

### Workflow Not Appearing

**Problem**: Don't see workflows in Actions tab

**Solution**:
1. Ensure .github/workflows/*.yml files are committed
2. Push to main branch
3. Wait 1-2 minutes
4. Refresh GitHub Actions page

### Secret Not Found Error

**Problem**: Workflow fails with "Secret not found"

**Solution**:
1. Verify secret exists in Settings → Secrets
2. Check spelling matches exactly (case-sensitive)
3. Ensure secret value is not empty
4. For kubeconfig, verify it's valid base64

### Kubeconfig Decode Error

**Problem**: Kubeconfig fails to decode

**Solution**:
```bash
# Test decode locally first
echo $KUBE_CONFIG_VALUE | base64 -d | kubectl cluster-info

# If it fails, re-encode:
cat ~/.kube/config | base64 | pbcopy  # macOS
cat ~/.kube/config | base64           # Linux

# Then update the secret with fresh base64
```

### Health Check Fails on First Run

**Problem**: Health check fails when no services deployed yet

**Solution**:
- This is normal on first run
- Deploy with Deploy to Kubernetes or Deploy to Docker first
- Then run health check
- Health check will work after services are running

### Deployment Timeout

**Problem**: Workflow times out waiting for pod readiness

**Solution**:
1. Check pod logs: `kubectl logs -n vapora <pod>`
2. Check pod description: `kubectl describe pod -n vapora <pod>`
3. Increase `rollout_timeout` input (default 300s)
4. Check resource requests/limits in deployment.yaml
5. Verify cluster has sufficient resources

---

## Next Steps

1. ✅ Setup workflows (you are here)
2. → Run first test deployment
3. → Configure Slack notifications
4. → Protect main and develop branches
5. → Train team on deployment process
6. → Monitor health checks
7. → Create runbook for incidents

---

## Support

- **Workflow Logs**: Check Actions → [Workflow] → [Run] → Logs
- **Artifacts**: Download from Actions → [Workflow] → [Run] → Artifacts
- **Issues**: Check GitHub Issues for auto-created failure reports
- **Slack**: Monitor #alerts channel for critical notifications

---

**Next**: Read [GITHUB_ACTIONS_GUIDE.md](./GITHUB_ACTIONS_GUIDE.md) for detailed workflow information