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)

# 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

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

# 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

# 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

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

git checkout -b feature/test-deployment

2. Make a Small Change

# 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

# 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

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

# 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 for detailed workflow information