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:

# 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

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

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

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)

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