POTE/docs/16_pipeline_setup.md

# 🔧 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.** 🎉