ilia/POTE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
POTE/BRANCH_SETUP_COMPLETE.md

7.7 KiB
Raw Blame History

✅ 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

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