aitbc/docs/policies/BRANCH_PROTECTION.md

Branch Protection Configuration Guide

Overview

This document outlines the recommended branch protection settings for the AITBC repository to ensure code quality, security, and collaboration standards.

GitHub Branch Protection Settings

Main Branch Protection

Navigate to: Settings > Branches > Branch protection rules

Create Protection Rule for main

Branch name pattern: main

Require status checks to pass before merging

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

Required status checks

• ✅ Lint (ruff)
• ✅ Check .env.example drift
• ✅ Test (pytest)
• ✅ contracts-ci / Lint
• ✅ contracts-ci / Slither Analysis
• ✅ contracts-ci / Compile
• ✅ contracts-ci / Test
• ✅ dotenv-check / dotenv-validation
• ✅ dotenv-check / dotenv-security
• ✅ security-scanning / bandit
• ✅ security-scanning / codeql
• ✅ security-scanning / safety
• ✅ security-scanning / trivy
• ✅ security-scanning / ossf-scorecard

Require pull request reviews before merging

• ✅ Require approvals
  • Required approving reviews: 2
• ✅ Dismiss stale PR approvals when new commits are pushed
• ✅ Require review from CODEOWNERS
• ✅ Require review from users with write access in the target repository
• ✅ Limit the number of approvals required (2) - Do not allow users with write access to approve their own pull requests

Restrict pushes

• ✅ Limit pushes to users who have write access in the repository
• ✅ Do not allow force pushes

Restrict deletions

• ✅ Do not allow users with write access to delete matching branches

Require signed commits

• ✅ Require signed commits (optional, for enhanced security)

Develop Branch Protection

Branch name pattern: develop

Settings (same as main, but with fewer required checks):

• Require status checks to pass before merging
• Required status checks: Lint, Test, Check .env.example drift
• Require pull request reviews before merging (1 approval)
• Limit pushes to users with write access
• Do not allow force pushes

Required Status Checks Configuration

Continuous Integration Checks

Status Check	Description	Workflow
Lint (ruff)	Python code linting	.github/workflows/ci.yml
Check .env.example drift	Configuration drift detection	.github/workflows/ci.yml
Test (pytest)	Python unit tests	.github/workflows/ci.yml
contracts-ci / Lint	Solidity linting	.github/workflows/contracts-ci.yml
contracts-ci / Slither Analysis	Solidity security analysis	.github/workflows/contracts-ci.yml
contracts-ci / Compile	Smart contract compilation	.github/workflows/contracts-ci.yml
contracts-ci / Test	Smart contract tests	.github/workflows/contracts-ci.yml
dotenv-check / dotenv-validation	.env.example format validation	.github/workflows/dotenv-check.yml
dotenv-check / dotenv-security	.env.example security check	.github/workflows/dotenv-check.yml
security-scanning / bandit	Python security scanning	.github/workflows/security-scanning.yml
security-scanning / codeql	CodeQL analysis	.github/workflows/security-scanning.yml
security-scanning / safety	Dependency vulnerability scan	.github/workflows/security-scanning.yml
security-scanning / trivy	Container security scan	.github/workflows/security-scanning.yml
security-scanning / ossf-scorecard	OSSF Scorecard analysis	.github/workflows/security-scanning.yml

Additional Checks for Feature Branches

For feature branches, consider requiring:

• comprehensive-tests / unit-tests
• comprehensive-tests / integration-tests
• comprehensive-tests / api-tests
• comprehensive-tests / blockchain-tests

CODEOWNERS Integration

The branch protection should be configured to require review from CODEOWNERS. This ensures that:

1. Domain experts review relevant changes
2. Security team reviews security-sensitive files
3. Core team reviews core functionality
4. Specialized teams review their respective areas

CODEOWNERS Rules Integration

# Security files require security team review
/security/ @aitbc/security-team
*.pem @aitbc/security-team

# Smart contracts require Solidity team review
/contracts/ @aitbc/solidity-team
*.sol @aitbc/solidity-team

# CLI changes require CLI team review
/cli/ @aitbc/cli-team
aitbc_cli/ @aitbc/cli-team

# Core files require core team review
pyproject.toml @aitbc/core-team
poetry.lock @aitbc/core-team

Pre-commit Hooks Integration

Branch protection works best with pre-commit hooks:

Required Pre-commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-json
      - id: check-toml
      - id: check-merge-conflict

  - repo: https://github.com/psf/black
    rev: 24.3.0
    hooks:
      - id: black
        language_version: python3.13

  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.1.15
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        args: [--ignore-missing-imports]

  - repo: local
    hooks:
      - id: dotenv-linter
        name: dotenv-linter
        entry: python scripts/focused_dotenv_linter.py
        language: system
        args: [--check]
        pass_filenames: false

Workflow Status Checks

CI Workflow Status

The CI workflows should be configured to provide clear status checks:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: ["**"]
  pull_request:
    branches: ["**"]

jobs:
  python:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.13'
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip poetry
          poetry config virtualenvs.create false
          poetry install --no-interaction --no-ansi
      
      - name: Lint (ruff)
        run: poetry run ruff check .
      
      - name: Check .env.example drift
        run: python scripts/focused_dotenv_linter.py --check
      
      - name: Test (pytest)
        run: poetry run pytest --cov=aitbc_cli --cov-report=term-missing --cov-report=xml

Security Best Practices

Commit Signing

Consider requiring signed commits for enhanced security:

# Configure GPG signing
git config --global commit.gpgsign true
git config --global user.signingkey YOUR_GPG_KEY_ID

Merge Methods

Configure merge methods for different branches:

• Main branch: Require squash merge with commit message validation
• Develop branch: Allow merge commits with proper PR description
• Feature branches: Allow any merge method

Release Branch Protection

For release branches (e.g., release/v1.0.0):

• Require all status checks
• Require 3 approving reviews
• Require review from release manager
• Require signed commits
• Do not allow force pushes or deletions

Enforcement Policies

Gradual Rollout

1. Phase 1: Enable basic protection (no force pushes, require PR reviews)
2. Phase 2: Add status checks for linting and testing
3. Phase 3: Add security scanning and comprehensive checks
4. Phase 4: Enable CODEOWNERS and signed commits

Exception Handling

Create a process for emergency bypasses:

1. Emergency changes: Allow bypass with explicit approval
2. Hotfixes: Temporary reduction in requirements
3. Documentation: All bypasses must be documented

Monitoring and Alerts

Set up monitoring for:

• Failed status checks
• Long-running PRs
• Bypass attempts
• Reviewer availability

Configuration as Code

GitHub Configuration

Use GitHub's API or Terraform to manage branch protection:

# Terraform example
resource "github_branch_protection" "main" {
  repository_id = github_repository.aitbc.node_id
  pattern        = "main"

  required_status_checks {
    strict   = true
    contexts = [
      "Lint (ruff)",
      "Check .env.example drift",
      "Test (pytest)",
      "contracts-ci / Lint",
      "contracts-ci / Slither Analysis",
      "contracts-ci / Compile",
      "contracts-ci / Test"
    ]
  }

  required_pull_request_reviews {
    required_approving_review_count = 2
    dismiss_stale_reviews          = true
    require_code_owner_reviews     = true
  }

  enforce_admins = true
}

Testing Branch Protection

Validation Tests

Create tests to validate branch protection:

def test_branch_protection_config():
    """Test that branch protection is properly configured"""
    # Test main branch protection
    main_protection = get_branch_protection("main")
    assert main_protection.required_status_checks == EXPECTED_CHECKS
    assert main_protection.required_approving_review_count == 2
    
    # Test develop branch protection
    develop_protection = get_branch_protection("develop")
    assert develop_protection.required_approving_review_count == 1

Integration Tests

Test that workflows work with branch protection:

def test_pr_with_branch_protection():
    """Test PR flow with branch protection"""
    # Create PR
    pr = create_pull_request()
    
    # Verify status checks run
    assert "Lint (ruff)" in pr.status_checks
    assert "Test (pytest)" in pr.status_checks
    
    # Verify merge is blocked until checks pass
    assert pr.mergeable == False

Troubleshooting

Common Issues

1. Status checks not appearing: Ensure workflows have proper names
2. CODEOWNERS not working: Verify team names and permissions
3. Pre-commit hooks failing: Check hook configuration and dependencies
4. Merge conflicts: Enable branch up-to-date requirements

Debugging Commands

# Check branch protection settings
gh api repos/aitbc/aitbc/branches/main/protection

# Check required status checks
gh api repos/aitbc/aitbc/branches/main/protection/required_status_checks

# Check CODEOWNERS rules
gh api repos/aitbc/aitbc/contents/CODEOWNERS

# Check recent workflow runs
gh run list --branch main

Documentation and Training

Team Guidelines

Create team guidelines for:

1. PR creation: How to create compliant PRs
2. Review process: How to conduct effective reviews
3. Bypass procedures: When and how to request bypasses
4. Troubleshooting: Common issues and solutions

Onboarding Checklist

New team members should be trained on:

1. Branch protection requirements
2. Pre-commit hook setup
3. CODEOWNERS review process
4. Status check monitoring

Conclusion

Proper branch protection configuration ensures code quality, security, and collaboration standards. By implementing these settings, the AITBC repository maintains high standards while enabling efficient development workflows.

Regular review and updates to branch protection settings ensure they remain effective as the project evolves.