POTE/docs/15_branch_setup_checklist.md

# ✅ 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.** 🚀