blackroad-operating-system/sop/templates/repo-template/.github/branch-protection.md

Branch Protection Configuration

This document specifies the branch protection rules to be applied to all BlackRoad project repositories.

Main Branch Protection

Branch: main

Settings

Require Pull Request:

• ✅ Require a pull request before merging
• Require approvals: 1
• Dismiss stale pull request approvals when new commits are pushed
• Require review from Code Owners (if CODEOWNERS file exists)

Status Checks:

• ✅ Require status checks to pass before merging
• ✅ Require branches to be up to date before merging

Required Status Checks:

• test (3.11)
• test (3.12)
• lint
• build
• security / summary (allow to fail)

Restrictions:

• ✅ Restrict who can push to matching branches
• Allowed to push: Repository admins only
• Allowed to bypass: None (not even admins)

Other Rules:

• ✅ Require linear history (enforce rebase or squash merge)
• ✅ Require deployments to succeed before merging (if applicable)
• ✅ Lock branch (prevent all changes) - ❌ Disabled (allow normal development)
• ✅ Do not allow force pushes
• ✅ Do not allow deletions

Enforcement:

• ✅ Include administrators (admins must follow the same rules)

---

Development Branch Protection (Optional)

Branch: develop (if using GitFlow)

Settings

Require Pull Request:

• ✅ Require a pull request before merging
• Require approvals: 1

Status Checks:

• ✅ Require status checks to pass before merging
• Required checks: test, lint, build

Other Rules:

• ✅ Do not allow force pushes
• ✅ Do not allow deletions

---

Tag Protection

Pattern: v* (all version tags)

Settings

• ✅ Only repository admins can create tags matching this pattern
• ✅ Only repository admins can delete tags matching this pattern

Purpose: Prevent accidental or malicious deletion of release tags

---

Implementation

Via GitHub API

Use this script to apply branch protection rules programmatically:

#!/bin/bash

REPO="blackboxprogramming/blackroad-{PROJECT_KEY}-backend"
BRANCH="main"
TOKEN="${GITHUB_TOKEN}"

curl -X PUT \
  "https://api.github.com/repos/${REPO}/branches/${BRANCH}/protection" \
  -H "Authorization: token ${TOKEN}" \
  -H "Accept: application/vnd.github.v3+json" \
  -d '{
    "required_status_checks": {
      "strict": true,
      "contexts": [
        "test (3.11)",
        "test (3.12)",
        "lint",
        "build"
      ]
    },
    "enforce_admins": true,
    "required_pull_request_reviews": {
      "dismissal_restrictions": {},
      "dismiss_stale_reviews": true,
      "require_code_owner_reviews": true,
      "required_approving_review_count": 1
    },
    "restrictions": null,
    "required_linear_history": true,
    "allow_force_pushes": false,
    "allow_deletions": false
  }'

Via GitHub Web UI

1. Go to repository → Settings → Branches
2. Click "Add branch protection rule"
3. Branch name pattern: main
4. Configure settings as specified above
5. Click "Create" or "Save changes"

---

CODEOWNERS File

Create .github/CODEOWNERS to automatically request reviews from specific teams:

# Default owners for everything
* @blackboxprogramming/engineering

# Backend code
/backend/ @blackboxprogramming/backend-team

# Frontend code
/frontend/ @blackboxprogramming/frontend-team

# Infrastructure
/ops/ @blackboxprogramming/devops-team
/terraform/ @blackboxprogramming/devops-team
/.github/workflows/ @blackboxprogramming/devops-team

# Documentation
/docs/ @blackboxprogramming/documentation-team
*.md @blackboxprogramming/documentation-team

# Security-sensitive files
/secrets/ @blackboxprogramming/security-team
.env.* @blackboxprogramming/security-team

---

Merge Strategy

Preferred: Squash and merge

Reasoning:

• Clean, linear history
• Each PR becomes a single commit
• Easy to revert if needed
• Clear attribution

Alternative: Rebase and merge (for repos with well-structured commit history)

Avoid: Merge commits (creates messy history)

---

Exceptions

When to bypass branch protection:

• NEVER for regular development
• Only in absolute emergencies:
  • Critical production bug fix (with manager approval)
  • Security vulnerability patch (with security team approval)
  • Service outage (with on-call engineer approval)

Process for emergency bypass:

1. Get approval in #ops or #engineering Slack channel
2. Document reason in channel
3. Make the emergency change
4. Create follow-up PR immediately after to document the change
5. Post-mortem within 24 hours

---

Monitoring

Weekly: Review bypass logs Monthly: Audit branch protection settings across all repos Quarterly: Review and update required status checks

Tool: Use GitHub audit log API to track who bypassed protection and why

---

Related

• GitHub Actions: CI Workflow
• New Client Kickoff Workflow
• Pull Request Template