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:

• Three branches (main, qa, dev)
• Main branch protection
• Comprehensive documentation
• CI/CD pipeline
• 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

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

- 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

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

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

# 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

# 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

# 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

$ 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. 🚀