Add branch setup completion guide and checklist
This commit is contained in:
ilia
parent
01597f608f
commit
9940100239
353
BRANCH_SETUP_COMPLETE.md
Normal file
353
BRANCH_SETUP_COMPLETE.md
Normal file
@ -0,0 +1,353 @@
|
||||
# ✅ Branch Strategy Setup Complete!
|
||||
|
||||
## 🌳 Branches Created
|
||||
|
||||
Your POTE repository now has three branches:
|
||||
|
||||
```
|
||||
✅ main (production) - PROTECTED
|
||||
✅ qa (staging) - Ready to protect
|
||||
✅ dev (development) - Ready to protect
|
||||
```
|
||||
|
||||
**Current status:**
|
||||
- `main` is already protected (you saw the error - that's good!)
|
||||
- New documentation committed to `dev` branch
|
||||
- Ready to configure protection for `qa` and `dev`
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Next Steps: Configure Branch Protection
|
||||
|
||||
### Go to Gitea: https://git.levkin.ca/ilia/POTE/settings/branches
|
||||
|
||||
### 1. Protect `main` (Production) - Already Done! ✅
|
||||
|
||||
Your `main` branch is already protected (we couldn't push directly to it).
|
||||
|
||||
**Verify settings:**
|
||||
- Branch name pattern: `main`
|
||||
- ✅ Enable push protection
|
||||
- ✅ Require pull request
|
||||
- ✅ Require approvals: 1 (or 2 for production)
|
||||
- ✅ Require status checks
|
||||
- ✅ Block force push
|
||||
- ✅ Block deletion
|
||||
|
||||
### 2. Protect `qa` (Staging) - TODO
|
||||
|
||||
Click "Add New Rule":
|
||||
- Branch name pattern: `qa`
|
||||
- ✅ Enable push protection
|
||||
- ✅ Require pull request
|
||||
- ✅ Require 1 approval
|
||||
- ✅ Require status checks to pass
|
||||
- ✅ Block force push
|
||||
- ✅ Block deletion
|
||||
|
||||
### 3. Configure `dev` (Development) - TODO
|
||||
|
||||
Click "Add New Rule":
|
||||
- Branch name pattern: `dev`
|
||||
- ✅ Require status checks to pass (CI must pass)
|
||||
- ⚠️ Allow direct push (for rapid development)
|
||||
- ✅ Block force push (optional)
|
||||
|
||||
---
|
||||
|
||||
## 📋 What You're Missing (Checklist)
|
||||
|
||||
### ✅ Already Have:
|
||||
- [x] Three branches (main, qa, dev)
|
||||
- [x] Main branch protection
|
||||
- [x] Comprehensive documentation
|
||||
- [x] CI/CD pipeline
|
||||
- [x] Gitea secrets integration
|
||||
|
||||
### 🔲 Need to Add:
|
||||
|
||||
#### 1. **Environment-Specific Secrets in Gitea**
|
||||
|
||||
Go to: https://git.levkin.ca/ilia/POTE/settings/secrets
|
||||
|
||||
**Development:**
|
||||
```
|
||||
DEV_HOST=10.0.10.100 (or your dev server IP)
|
||||
DEV_USER=poteapp
|
||||
DEV_SSH_KEY=(SSH key for dev server)
|
||||
SMTP_PASSWORD_DEV=(dev email password)
|
||||
DB_PASSWORD_DEV=dev_password_123
|
||||
```
|
||||
|
||||
**QA/Staging:**
|
||||
```
|
||||
QA_HOST=10.0.10.101 (or your QA server IP)
|
||||
QA_USER=poteapp
|
||||
QA_SSH_KEY=(SSH key for QA server)
|
||||
SMTP_PASSWORD_QA=(qa email password)
|
||||
DB_PASSWORD_QA=qa_password_123
|
||||
```
|
||||
|
||||
**Production:**
|
||||
```
|
||||
PROXMOX_HOST=10.0.10.95 (already have this)
|
||||
PROXMOX_USER=poteapp
|
||||
PROXMOX_SSH_KEY=(already have this)
|
||||
SMTP_PASSWORD=(already have this)
|
||||
DB_PASSWORD=changeme123
|
||||
```
|
||||
|
||||
#### 2. **Create Environment-Specific Deployment Workflows**
|
||||
|
||||
Files to create:
|
||||
- `.github/workflows/deploy-dev.yml` (see docs/14_branch_strategy_and_deployment.md)
|
||||
- `.github/workflows/deploy-qa.yml`
|
||||
- `.github/workflows/deploy-prod.yml` (already have deploy.yml, can rename/update)
|
||||
|
||||
#### 3. **Set Up Separate Servers/Containers**
|
||||
|
||||
You need three environments:
|
||||
|
||||
| Environment | Server/Container | Database | Purpose |
|
||||
|-------------|------------------|----------|---------|
|
||||
| **Dev** | `10.0.10.100` (or new LXC) | `potedb_dev` | Development testing |
|
||||
| **QA** | `10.0.10.101` (or new LXC) | `potedb_qa` | Pre-production testing |
|
||||
| **Prod** | `10.0.10.95` (existing) | `potedb` | Production |
|
||||
|
||||
**Options:**
|
||||
- Create 2 more LXC containers (recommended)
|
||||
- Use same server with different ports/databases
|
||||
- Use Docker containers
|
||||
|
||||
#### 4. **Ansible Integration**
|
||||
|
||||
**Option A: Gitea Webhooks**
|
||||
```
|
||||
Gitea → Settings → Webhooks → Add Webhook
|
||||
URL: https://your-ansible-controller/webhook/pote
|
||||
Trigger on: Push events
|
||||
Branches: dev, qa, main
|
||||
```
|
||||
|
||||
**Option B: Gitea Actions calls Ansible**
|
||||
```yaml
|
||||
# In workflow
|
||||
- name: Trigger Ansible
|
||||
run: |
|
||||
curl -X POST https://ansible-controller/api/deploy \
|
||||
-d '{"branch": "${{ github.ref_name }}"}'
|
||||
```
|
||||
|
||||
#### 5. **Update Ansible Playbook**
|
||||
|
||||
Your Ansible playbook should:
|
||||
```yaml
|
||||
- name: Deploy POTE
|
||||
hosts: "{{ target_env }}"
|
||||
vars:
|
||||
branch: "{{ git_branch }}" # dev, qa, or main
|
||||
tasks:
|
||||
- git:
|
||||
repo: gitea@10.0.30.169:ilia/POTE.git
|
||||
dest: /home/poteapp/pote
|
||||
version: "{{ branch }}"
|
||||
# ... rest of deployment
|
||||
```
|
||||
|
||||
#### 6. **Database Migration Strategy**
|
||||
|
||||
```bash
|
||||
# Always test in dev first
|
||||
ssh poteapp@dev-server "cd ~/pote && alembic upgrade head"
|
||||
|
||||
# Then QA
|
||||
ssh poteapp@qa-server "cd ~/pote && alembic upgrade head"
|
||||
|
||||
# Finally prod (with backup!)
|
||||
ssh poteapp@prod-server "pg_dump potedb > backup.sql && cd ~/pote && alembic upgrade head"
|
||||
```
|
||||
|
||||
#### 7. **Monitoring & Alerts**
|
||||
|
||||
Add to each deployment:
|
||||
```yaml
|
||||
- name: Health Check
|
||||
run: python scripts/health_check.py
|
||||
|
||||
- name: Send Alert on Failure
|
||||
if: failure()
|
||||
run: |
|
||||
# Send email/Slack notification
|
||||
```
|
||||
|
||||
#### 8. **Environment Variables**
|
||||
|
||||
Create separate configs:
|
||||
- `.env.dev` (in dev server)
|
||||
- `.env.qa` (in qa server)
|
||||
- `.env` (in prod server - already have)
|
||||
|
||||
**Never commit these!** Use Ansible templates or deployment workflows.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Workflow After Setup
|
||||
|
||||
### Development Flow:
|
||||
|
||||
```bash
|
||||
# 1. Work on feature
|
||||
git checkout dev
|
||||
git pull origin dev
|
||||
# ... make changes ...
|
||||
git commit -m "Add feature"
|
||||
git push origin dev
|
||||
|
||||
# 2. Auto-deploys to DEV server
|
||||
# (via Gitea webhook or Actions)
|
||||
|
||||
# 3. Test in DEV
|
||||
|
||||
# 4. Promote to QA
|
||||
# Create PR: dev → qa in Gitea UI
|
||||
# Merge after approval
|
||||
# Auto-deploys to QA server
|
||||
|
||||
# 5. QA Testing
|
||||
|
||||
# 6. Promote to PROD
|
||||
# Create PR: qa → main in Gitea UI
|
||||
# Requires 2 approvals
|
||||
# Merge
|
||||
# Manual deployment trigger (with confirmation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
**Main guide:** `docs/14_branch_strategy_and_deployment.md`
|
||||
|
||||
Covers:
|
||||
- ✅ Branch protection setup
|
||||
- ✅ Multi-environment workflows
|
||||
- ✅ Ansible integration
|
||||
- ✅ Deployment flow
|
||||
- ✅ Rollback procedures
|
||||
- ✅ Complete checklist
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Actions (Do These Now)
|
||||
|
||||
### 1. Configure Branch Protection (5 minutes)
|
||||
|
||||
```
|
||||
https://git.levkin.ca/ilia/POTE/settings/branches
|
||||
- Add rule for 'qa'
|
||||
- Add rule for 'dev'
|
||||
```
|
||||
|
||||
### 2. Add Environment Secrets (10 minutes)
|
||||
|
||||
```
|
||||
https://git.levkin.ca/ilia/POTE/settings/secrets
|
||||
- Add DEV_* secrets
|
||||
- Add QA_* secrets
|
||||
- Verify PROD secrets exist
|
||||
```
|
||||
|
||||
### 3. Create PR for Documentation (2 minutes)
|
||||
|
||||
```
|
||||
https://git.levkin.ca/ilia/POTE/compare/main...dev
|
||||
- Create pull request
|
||||
- Title: "Add branch strategy documentation"
|
||||
- Merge to main
|
||||
```
|
||||
|
||||
### 4. Decide on Server Setup
|
||||
|
||||
**Option 1:** Create 2 more LXC containers
|
||||
```bash
|
||||
# On Proxmox host
|
||||
pct clone 100 101 --hostname pote-dev
|
||||
pct clone 100 102 --hostname pote-qa
|
||||
```
|
||||
|
||||
**Option 2:** Use existing server with different databases
|
||||
```bash
|
||||
# On existing server
|
||||
createdb potedb_dev
|
||||
createdb potedb_qa
|
||||
```
|
||||
|
||||
### 5. Configure Ansible
|
||||
|
||||
Update your Ansible inventory to include:
|
||||
- `pote-dev` host
|
||||
- `pote-qa` host
|
||||
- `pote-prod` host (existing)
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important Notes
|
||||
|
||||
### Main Branch is Protected!
|
||||
|
||||
You saw this error:
|
||||
```
|
||||
remote: Gitea: Not allowed to push to protected branch main
|
||||
```
|
||||
|
||||
**This is GOOD!** It means:
|
||||
- ✅ Main branch is protected
|
||||
- ✅ Can't accidentally push directly
|
||||
- ✅ Must use Pull Requests
|
||||
- ✅ Requires code review
|
||||
|
||||
**To update main:**
|
||||
1. Push to `dev` or `qa`
|
||||
2. Create Pull Request in Gitea
|
||||
3. Get approval
|
||||
4. Merge
|
||||
|
||||
### Current Branch Status
|
||||
|
||||
```bash
|
||||
$ git branch
|
||||
dev ← New documentation is here
|
||||
* main ← Protected, can't push directly
|
||||
qa ← Empty, same as main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- **Repository:** https://git.levkin.ca/ilia/POTE
|
||||
- **Branch Protection:** https://git.levkin.ca/ilia/POTE/settings/branches
|
||||
- **Secrets:** https://git.levkin.ca/ilia/POTE/settings/secrets
|
||||
- **Actions:** https://git.levkin.ca/ilia/POTE/actions
|
||||
- **Create PR:** https://git.levkin.ca/ilia/POTE/compare/main...dev
|
||||
|
||||
---
|
||||
|
||||
## ✅ Summary
|
||||
|
||||
**What's Done:**
|
||||
- ✅ Created `dev`, `qa`, `main` branches
|
||||
- ✅ Main branch is protected
|
||||
- ✅ Documentation committed to `dev`
|
||||
- ✅ Ready for Ansible integration
|
||||
|
||||
**What's Next:**
|
||||
1. Configure branch protection for `qa` and `dev`
|
||||
2. Add environment-specific secrets
|
||||
3. Create PR to merge docs to main
|
||||
4. Set up dev/qa servers
|
||||
5. Configure Ansible for multi-environment
|
||||
6. Test deployment flow
|
||||
|
||||
**You're 80% there! Just need to configure Gitea settings and set up the additional servers.** 🚀
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user