Skip to content

github-branch-protection.md

Latest commit

 

History

History
162 lines (124 loc) · 5.97 KB

github-branch-protection.md

File metadata and controls

162 lines (124 loc) · 5.97 KB
Raw

GitHub Branch Protection Configuration

Overview

This document outlines the recommended branch protection rules for the main branch in this repository. These settings are designed to provide safety and structure while accommodating a solo developer workflow.

Accessing Branch Protection Settings

  1. Navigate to your repository on GitHub
  2. Click Settings → Branches (in the left sidebar)
  3. Under "Branch protection rules", click Add rule
  4. Enter main as the branch name pattern
  5. Configure the settings as described below

Recommended Settings for Solo Developer

✅ Essential Protections

1. Prevent Force Pushes

  • Setting: Check "Do not allow force pushes"
  • Rationale: Prevents accidental history rewrites that could cause data loss
  • Impact: You can still push normally, but cannot use git push --force

2. Prevent Branch Deletion

  • Setting: Check "Do not allow deletions"
  • Rationale: Protects the main branch from accidental deletion
  • Impact: The main branch cannot be deleted through the GitHub UI or API

🔄 Optional But Recommended

3. Require Pull Request Before Merging

  • Setting: Check "Require a pull request before merging"
  • Sub-setting: Set "Required approvals" to 0
  • Rationale:
    • Forces you to work on feature branches
    • Provides a review checkpoint even for solo work
    • GitHub Copilot can assist with code review
    • Creates a clean audit trail of changes
  • Impact: You cannot push directly to main; must create PRs from feature branches
  • Solo Developer Note: With 0 required approvals, you can merge your own PRs immediately after creation

4. Require Status Checks (If Using CI/CD)

  • Setting: Check "Require status checks to pass before merging"
  • Rationale: Ensures automated tests and builds pass before merging
  • Impact: PRs cannot be merged if CI/CD checks fail
  • Note: Only enable if you have GitHub Actions workflows or other CI/CD configured

5. Require Conversation Resolution

  • Setting: Check "Require conversation resolution before merging"
  • Rationale: Ensures you've addressed any comments or notes left during review
  • Impact: All PR comments must be marked as resolved before merging
  • Solo Developer Note: Useful for tracking your own review notes and TODOs

6. Require Linear History

  • Setting: Check "Require linear history"
  • Rationale: Maintains a clean, linear git history without merge commits
  • Impact: Only allows squash merges or rebase merges for PRs
  • Solo Developer Note: Recommended for cleaner history

⚠️ Settings to Skip for Solo Developer

❌ Do NOT Enable: Require Approvals from Code Owners

  • Rationale: Not practical for solo development
  • Alternative: Use CODEOWNERS for documentation purposes only

❌ Do NOT Enable: Restrict Who Can Push

  • Rationale: Unnecessary when you're the only developer
  • Note: You're already the admin/owner

❌ Do NOT Enable: Required Reviewers Count > 0

  • Rationale: You cannot review your own PRs
  • Alternative: Set to 0 approvals if using PR workflow

Suggested Configuration Summary

Minimal Configuration (Essential Only)

Branch name pattern: main
☑ Do not allow force pushes
☑ Do not allow deletions

Recommended Configuration (Balanced)

Branch name pattern: main
☑ Require a pull request before merging
  ☑ Require approvals: 0
  ☑ Dismiss stale pull request approvals when new commits are pushed
☑ Require status checks to pass before merging (if using CI/CD)
  - Add your workflow status checks here
☑ Require conversation resolution before merging
☑ Require linear history
☑ Do not allow force pushes
☑ Do not allow deletions

Workflow with Branch Protection

Typical Development Flow

  1. Create a feature branch:

    git checkout -b feature/my-new-feature

  2. Make your changes and commit:

    git add .
git commit -m "Add new feature"
git push origin feature/my-new-feature

  3. Create a Pull Request:

    • Go to GitHub and create a PR from your feature branch to main
    • Review the changes yourself (or use GitHub Copilot for suggestions)
    • Ensure all status checks pass (if configured)

  4. Merge the PR:

    • If using 0 required approvals, you can merge immediately
    • Choose merge strategy (squash recommended for linear history)
    • Delete the feature branch after merging

  5. Update your local main branch:

    git checkout main
git pull origin main

Benefits of This Approach

  1. Safety: Main branch is protected from accidental deletion or force pushes
  2. Clean History: Linear history with meaningful PR descriptions
  3. Documentation: Each PR serves as documentation for why changes were made
  4. Flexibility: You can still work quickly as a solo developer
  5. Best Practices: Prepares the workflow for potential future collaborators
  6. AI Assistance: GitHub Copilot can provide code review suggestions on PRs

Exceptions and Overrides

As the repository owner/admin, you can always:

  • Temporarily disable branch protection if absolutely necessary
  • Override protection rules in emergency situations
  • Modify protection settings at any time

However, avoid making exceptions habitual to maintain good development practices.

Additional Resources

Review Schedule

Review and update these settings:

  • When adding collaborators to the repository
  • When implementing CI/CD workflows
  • When changing development workflow
  • Quarterly as a best practice

Last Updated: 2025-11-16