turbovault-app/docs/GITHUB_ACTIONS_SETUP.md

GitHub Actions Setup Complete! 🎉

Your repository is now configured with GitHub Actions for automated building and deployment.

What's Been Added

GitHub Actions Workflows

1. .github/workflows/build-and-push.yml

Purpose: Build Docker image and push to your Gitea registry

Triggers:

• ✅ When you push a version tag (e.g., v1.0.0, v2.1.0)
• ✅ Manual trigger from GitHub Actions tab

What it does:

1. Checks out your code
2. Builds Docker image
3. Logs into your Gitea registry
4. Pushes image with version tag + latest tag
5. Shows deploy command in output

2. .github/workflows/ci.yml

Purpose: Run tests and quality checks

Triggers:

• ✅ On push to main or develop branches
• ✅ On pull requests

What it does:

1. Lint: Runs RuboCop (code style)
2. Security: Runs Brakeman (security scan)
3. Test: Runs your test suite with PostgreSQL
4. Build Test: Verifies Dockerfile builds successfully

Documentation

• ✅ .github/SECRETS_SETUP.md - How to configure GitHub Secrets
• ✅ .github/WHAT_TO_COMMIT.md - What's safe to commit publicly
• ✅ GITHUB_ACTIONS_SETUP.md - This file!

Updated Files

• ✅ README.md - Added CI/CD section
• ✅ k8s/deployment.yaml - Placeholder image paths
• ✅ k8s/migrate-job.yaml - Placeholder image paths
• ✅ .gitignore - Already excludes secrets ✅

Your Next Steps

Step 1: Add GitHub Secrets

Go to your GitHub repository → Settings → Secrets and variables → Actions

Add these 4 secrets:

Secret Name	Value	Example
GITEA_REGISTRY	Your Gitea URL (no https://)	gitea.example.com
GITEA_USERNAME	Your Gitea username	johndoe
GITEA_TOKEN	Gitea access token	gtea_abc123...
GITEA_REPO	Repo path	johndoe/turbovault

Detailed instructions: .github/SECRETS_SETUP.md

Step 2: Get Gitea Access Token

1. Login to your Gitea instance
2. Settings → Applications → Manage Access Tokens
3. Click Generate New Token
4. Name: github-actions
5. Permissions:
   • ✅ package:read
   • ✅ package:write
6. Click Generate Token
7. Copy the token (starts with gtea_)
8. Add to GitHub as GITEA_TOKEN secret

Step 3: Push to GitHub

# Make sure you're in the project directory
cd turbovault-web

# Run the setup script
./scripts/setup-github.sh

# Or manually:
git add .
git commit -m "Add GitHub Actions for CI/CD"
git push origin main

Step 4: Test the Workflow

Option A: Manually trigger a build

1. Go to your GitHub repository
2. Click Actions tab
3. Click Build and Push to Gitea
4. Click Run workflow button
5. Enter tag: test or v0.1.0
6. Click Run workflow
7. Watch it build!

Option B: Create a version tag

# Create and push a tag
git tag v1.0.0
git push origin v1.0.0

# This will automatically trigger the build workflow

Step 5: Verify Image in Gitea

1. Login to your Gitea instance
2. Go to your repository
3. Click Packages tab
4. You should see turbovault package with your tag

Step 6: Deploy to Kubernetes

# Update deployment with new image
kubectl set image deployment/turbovault \
  turbovault=gitea.example.com/username/turbovault:v1.0.0 \
  -n turbovault

# Or use the deployment script
./scripts/deploy-k8s.sh

Workflow Explained

Build Flow

┌─────────────────────────────────────────────────────┐
│  Developer pushes tag: git push origin v1.0.0      │
└─────────────────────┬───────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  GitHub Actions detects tag                         │
│  Workflow: build-and-push.yml                       │
└─────────────────────┬───────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  1. Checkout code from GitHub                       │
│  2. Build Docker image                              │
│  3. Login to Gitea registry (using secrets)         │
│  4. Tag image: v1.0.0 + latest                      │
│  5. Push to Gitea                                   │
└─────────────────────┬───────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  Image available in Gitea package registry          │
│  gitea.example.com/username/turbovault:v1.0.0      │
└─────────────────────┬───────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  Deploy to Kubernetes (manual or automated)         │
│  kubectl set image deployment/turbovault ...        │
└─────────────────────────────────────────────────────┘

CI Flow

┌─────────────────────────────────────────────────────┐
│  Developer pushes code or opens PR                  │
└─────────────────────┬───────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  GitHub Actions runs ci.yml workflow                │
└─────────────────────┬───────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  Parallel jobs:                                     │
│  ├─ Lint (RuboCop)                                  │
│  ├─ Security (Brakeman)                             │
│  ├─ Test (RSpec/Minitest with PostgreSQL)          │
│  └─ Build Test (Docker build verification)         │
└─────────────────────┬───────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────┐
│  ✅ All checks pass → Merge safe                    │
│  ❌ Checks fail → Fix issues before merge           │
└─────────────────────────────────────────────────────┘

Common Tasks

Release a New Version

# 1. Make changes and commit
git add .
git commit -m "Add new feature"
git push origin main

# 2. Wait for CI to pass (check Actions tab)

# 3. Create release tag
git tag v1.1.0
git push origin v1.1.0

# 4. GitHub Actions builds and pushes to Gitea automatically

# 5. Deploy to k8s
kubectl set image deployment/turbovault \
  turbovault=gitea.example.com/username/turbovault:v1.1.0 \
  -n turbovault

Rollback to Previous Version

# Deploy previous tag
kubectl set image deployment/turbovault \
  turbovault=gitea.example.com/username/turbovault:v1.0.0 \
  -n turbovault

# Watch rollout
kubectl rollout status deployment/turbovault -n turbovault

View Build Logs

1. Go to GitHub repository
2. Click Actions tab
3. Click on a workflow run
4. Click on job name to see logs

Rebuild Latest

# Delete and recreate tag (forces rebuild)
git tag -d latest
git push origin :refs/tags/latest
git tag latest
git push origin latest

Troubleshooting

Build fails with "unauthorized"

Problem: Can't login to Gitea registry

Solution:

1. Verify GITEA_TOKEN in GitHub secrets is correct
2. Check token has package:write permission
3. Test locally: docker login gitea.example.com

Image pushes but k8s can't pull

Problem: ImagePullBackOff in Kubernetes

Solution:

1. Verify k8s secret exists: kubectl get secret gitea-registry -n turbovault
2. Check imagePullSecrets in deployment.yaml
3. See k8s/GITEA_SETUP.md

CI tests fail

Problem: Tests don't pass in GitHub Actions

Solution:

1. Run tests locally: rails test
2. Check PostgreSQL connection
3. Review test logs in Actions tab
4. Tests are set to continue-on-error: true for now (won't block builds)

Workflow doesn't trigger

Problem: Pushing tag doesn't start build

Solution:

1. Check tag format: must be v*.*.* (e.g., v1.0.0)
2. Verify workflow file exists: .github/workflows/build-and-push.yml
3. Check Actions tab for errors

Benefits

✅ What You Get

1. Automated Builds - No manual Docker commands
2. Version Control - Each tag creates a versioned image
3. CI/CD Pipeline - Auto-test every change
4. Quality Checks - Linting and security scans
5. Rollback Safety - Keep all versions in Gitea
6. Collaboration - Contributors get CI feedback on PRs

🎯 Workflow Benefits

• For You: Push tag → image automatically builds → deploy
• For Contributors: Submit PR → auto-tested → you review
• For Production: Tagged releases → immutable versions → safe rollbacks

Next Steps

1. ✅ Add GitHub Secrets (.github/SECRETS_SETUP.md)
2. ✅ Push code to GitHub
3. ✅ Test workflow (manual trigger or push tag)
4. ✅ Verify image in Gitea
5. ✅ Deploy to Kubernetes
6. ✅ Celebrate! 🎉

Questions?

• "Do I need to push to Gitea too?" → No! GitHub Actions does it for you
• "What about the source code?" → Push to GitHub, images go to Gitea automatically
• "Can I still build locally?" → Yes! Docker build commands still work
• "Do contributors need Gitea access?" → No! Only you need it (for GitHub Secrets)
• "How do I disable a workflow?" → GitHub → Actions → Select workflow → Disable

---

You're all set! Add your GitHub Secrets and push a tag to see it in action! 🚀

For detailed instructions, see:

• .github/SECRETS_SETUP.md - Configure secrets
• k8s/GITEA_SETUP.md - Gitea registry setup
• DEPLOYMENT.md - Full deployment guide