Add pipeline setup guide for branch protection
This commit is contained in:
ilia
parent
3910ca9d04
commit
659896f096
378
PIPELINE_SETUP_GUIDE.md
Normal file
378
PIPELINE_SETUP_GUIDE.md
Normal file
@ -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.** 🎉
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user