From 659896f09652b92c60c027aa1025be2b9cb35db4 Mon Sep 17 00:00:00 2001
From: ilia <ilia@levkin.ca>
Date: Wed, 24 Dec 2025 21:54:25 -0500
Subject: [PATCH] Add pipeline setup guide for branch protection

---
 PIPELINE_SETUP_GUIDE.md | 378 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 378 insertions(+)
 create mode 100644 PIPELINE_SETUP_GUIDE.md

diff --git a/PIPELINE_SETUP_GUIDE.md b/PIPELINE_SETUP_GUIDE.md
new file mode 100644
index 0000000..a01b24c
--- /dev/null
+++ b/PIPELINE_SETUP_GUIDE.md
@@ -0,0 +1,378 @@
+# 🔧 Pipeline Setup Guide for Branch Protection
+
+## ❓ Do You Need a Pipeline?
+
+**YES!** If you want to use "Require status checks" in branch protection, you need a CI pipeline.
+
+**Good news:** You already have one! ✅
+
+---
+
+## ✅ What You Already Have
+
+### CI Pipeline: `.github/workflows/ci.yml`
+
+**Status:** ✅ Exists and working
+**Runs on:** Push to `main`, `qa`, `dev` (just updated!)
+**What it does:**
+- Runs linters (ruff, black, mypy)
+- Runs 93 tests
+- Checks code quality
+- Uses PostgreSQL for integration tests
+
+---
+
+## 🚀 Setup Order (IMPORTANT!)
+
+### ⚠️ **DO THIS IN ORDER:**
+
+### Step 1: Merge CI Updates to Main (FIRST!)
+
+**Why:** Branch protection needs the CI pipeline to exist in the branch you're protecting.
+
+**How:**
+1. Go to: https://git.levkin.ca/ilia/POTE/compare/main...dev
+2. Click "New Pull Request"
+3. Title: "Update CI for multi-branch support"
+4. **Merge this PR** (you can merge without protection for now)
+
+**What this does:**
+- Updates CI to run on `main`, `qa`, and `dev`
+- Makes CI available for branch protection
+
+---
+
+### Step 2: Verify CI is Working
+
+After merging the PR, check:
+1. Go to: https://git.levkin.ca/ilia/POTE/actions
+2. You should see the CI workflow running
+3. Wait for it to complete (green checkmark ✅)
+
+**If CI fails:**
+- Don't set up branch protection yet
+- Fix the CI issues first
+- Ensure tests pass
+
+---
+
+### Step 3: Configure Branch Protection (AFTER CI WORKS)
+
+**Only after CI is passing**, go to:
+https://git.levkin.ca/ilia/POTE/settings/branches
+
+#### For `main` Branch (Already Protected)
+
+**Verify these settings:**
+- Branch pattern: `main`
+- ✅ Enable push protection
+- ✅ Require pull request
+- ✅ Require 1-2 approvals
+- ✅ **Require status checks to pass before merging**
+  - Select: `CI / lint-and-test` (this appears after CI runs once)
+- ✅ Block force push
+- ✅ Block deletion
+
+#### For `qa` Branch
+
+Click "Add New Rule":
+- Branch pattern: `qa`
+- ✅ Enable push protection
+- ✅ Require pull request
+- ✅ Require 1 approval
+- ✅ **Require status checks to pass before merging**
+  - Select: `CI / lint-and-test`
+- ✅ Block force push
+- ✅ Block deletion
+
+#### For `dev` Branch
+
+Click "Add New Rule":
+- Branch pattern: `dev`
+- ✅ **Require status checks to pass before merging**
+  - Select: `CI / lint-and-test`
+- ⚠️ **Allow direct push** (no PR required for dev)
+- ⚠️ Allow force push (optional, for rebasing)
+
+---
+
+## 🔍 What "Require Status Checks" Means
+
+When you enable "Require status checks":
+
+**Before merge:**
+```
+PR created: dev → qa
+    ↓
+CI pipeline runs automatically
+    ↓
+Tests must pass ✅
+    ↓
+Only then can you merge
+```
+
+**If CI fails:**
+```
+PR created: dev → qa
+    ↓
+CI pipeline runs
+    ↓
+Tests fail ❌
+    ↓
+Merge button is DISABLED
+    ↓
+Must fix code and push again
+```
+
+---
+
+## 📋 Status Checks Available
+
+After your CI runs once, you'll see these options in branch protection:
+
+**Available checks:**
+- `CI / lint-and-test` - Main CI pipeline (93 tests)
+- `CI / security-scan` - Security scanning
+- `CI / dependency-scan` - Dependency vulnerabilities
+- `CI / docker-build-test` - Docker build verification
+
+**Recommended:**
+- **For `main`:** Require ALL checks ✅
+- **For `qa`:** Require `lint-and-test` + `security-scan` ✅
+- **For `dev`:** Require `lint-and-test` only ✅
+
+---
+
+## 🎯 Step-by-Step Setup (Complete)
+
+### 1. Merge CI Updates (5 minutes)
+
+```
+1. Go to: https://git.levkin.ca/ilia/POTE/compare/main...dev
+2. Create PR: "Update CI for multi-branch support"
+3. Merge (you can approve your own PR for now)
+4. Wait for CI to run on main branch
+```
+
+### 2. Check CI Status (2 minutes)
+
+```
+1. Go to: https://git.levkin.ca/ilia/POTE/actions
+2. Click on the latest workflow run
+3. Verify all jobs pass ✅
+```
+
+### 3. Configure Branch Protection (10 minutes)
+
+```
+1. Go to: https://git.levkin.ca/ilia/POTE/settings/branches
+
+2. For main (update existing rule):
+   - ✅ Require status checks
+   - Select: CI / lint-and-test
+
+3. Add rule for qa:
+   - Branch: qa
+   - ✅ Require PR
+   - ✅ Require status checks
+   - Select: CI / lint-and-test
+
+4. Add rule for dev:
+   - Branch: dev
+   - ✅ Require status checks
+   - Select: CI / lint-and-test
+   - ⚠️ Allow direct push
+```
+
+---
+
+## ⚠️ Common Issues
+
+### Issue 1: "No status checks found"
+
+**Cause:** CI hasn't run on that branch yet
+
+**Fix:**
+```bash
+# Push something to trigger CI
+git checkout dev
+git commit --allow-empty -m "Trigger CI"
+git push origin dev
+
+# Wait for CI to run, then configure protection
+```
+
+### Issue 2: "Status check never completes"
+
+**Cause:** CI is failing or stuck
+
+**Fix:**
+1. Go to Actions tab
+2. Check the failing job
+3. Fix the issue
+4. Push again
+
+### Issue 3: "Can't select status checks in dropdown"
+
+**Cause:** CI workflow name doesn't match
+
+**Fix:**
+- Workflow must be named exactly: `CI`
+- Job must be named: `lint-and-test`
+- Already correct in your `.github/workflows/ci.yml` ✅
+
+---
+
+## 🧪 Test Your Setup
+
+### After configuring protection:
+
+**Test 1: Try to push directly to main**
+```bash
+git checkout main
+git commit --allow-empty -m "Test"
+git push origin main
+# Should fail: "Not allowed to push to protected branch"
+```
+
+**Test 2: Create PR with failing tests**
+```bash
+git checkout dev
+# Break a test intentionally
+git commit -m "Break test"
+git push origin dev
+# Create PR to qa
+# Merge button should be disabled until CI passes
+```
+
+**Test 3: Create PR with passing tests**
+```bash
+git checkout dev
+# Fix the test
+git commit -m "Fix test"
+git push origin dev
+# Create PR to qa
+# Merge button should be enabled after CI passes ✅
+```
+
+---
+
+## 📊 What Happens After Setup
+
+### Workflow with Protection:
+
+```
+Developer pushes to dev
+    ↓
+CI runs automatically
+    ↓
+✅ Tests pass
+    ↓
+Developer creates PR: dev → qa
+    ↓
+CI runs on PR
+    ↓
+✅ Tests pass
+    ↓
+Reviewer approves
+    ↓
+✅ Merge button enabled
+    ↓
+Merge to qa
+    ↓
+CI runs on qa branch
+    ↓
+✅ Tests pass
+    ↓
+Auto-deploy to QA server (if configured)
+```
+
+**If tests fail at any point:**
+```
+CI runs
+    ↓
+❌ Tests fail
+    ↓
+Merge button DISABLED
+    ↓
+Developer fixes code
+    ↓
+Pushes again
+    ↓
+CI runs again
+    ↓
+Loop until tests pass ✅
+```
+
+---
+
+## ✅ Checklist
+
+Before configuring branch protection:
+- [ ] CI workflow exists (`.github/workflows/ci.yml`) ✅
+- [ ] CI runs on all branches (`main`, `qa`, `dev`) ✅
+- [ ] CI has run at least once on each branch
+- [ ] All tests are passing ✅
+- [ ] You can see workflow runs in Actions tab
+
+After configuring:
+- [ ] `main` branch requires status checks
+- [ ] `qa` branch requires status checks
+- [ ] `dev` branch requires status checks
+- [ ] Tested: Can't push directly to `main`
+- [ ] Tested: PR merge blocked when CI fails
+- [ ] Tested: PR merge allowed when CI passes
+
+---
+
+## 🎯 Quick Start (TL;DR)
+
+```bash
+# 1. Merge CI updates
+# Go to: https://git.levkin.ca/ilia/POTE/compare/main...dev
+# Create and merge PR
+
+# 2. Wait for CI to run
+# Check: https://git.levkin.ca/ilia/POTE/actions
+
+# 3. Configure branch protection
+# Go to: https://git.levkin.ca/ilia/POTE/settings/branches
+# Add rules for main, qa, dev
+# Enable "Require status checks"
+# Select "CI / lint-and-test"
+
+# Done! ✅
+```
+
+---
+
+## 📚 Related Documentation
+
+- **CI Workflow:** `.github/workflows/ci.yml`
+- **Branch Strategy:** `docs/14_branch_strategy_and_deployment.md`
+- **Setup Checklist:** `BRANCH_SETUP_COMPLETE.md`
+- **Gitea Secrets:** `GITEA_SECRETS_GUIDE.md`
+
+---
+
+## 🚀 Summary
+
+**Do you need a pipeline?**
+- ✅ YES, to use "Require status checks"
+- ✅ You already have one!
+- ✅ Just need to merge it to main first
+
+**Setup order:**
+1. Merge CI updates to main (via PR)
+2. Verify CI runs and passes
+3. Configure branch protection
+4. Test the protection
+
+**After setup:**
+- All branches protected by CI
+- Can't merge failing code
+- Professional development workflow
+- Ready for Ansible integration
+
+**You're almost there! Just merge the PR and configure protection.** 🎉
+