mirror of
https://github.com/ryankazokas/turbovault-app.git
synced 2026-04-17 07:52:53 +00:00
Moving to github
This commit is contained in:
326
docs/GITHUB_ACTIONS_SETUP.md
Normal file
326
docs/GITHUB_ACTIONS_SETUP.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# 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](../.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
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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](../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](../.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](../.github/SECRETS_SETUP.md) - Configure secrets
|
||||
- [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) - Gitea registry setup
|
||||
- [DEPLOYMENT.md](DEPLOYMENT.md) - Full deployment guide
|
||||
Reference in New Issue
Block a user