Skip to content

Repository Hygiene (PR rules, protections)

Repository Hygiene (PR rules, protections)

Overview

Protect your main branch and enforce good practices so merges into main are safe, reviewed, and validated by automation. This reduces regressions and keeps your project healthy.

Key branch protection settings to enable

  • Require a pull request before merging (disable direct pushes to main).
  • Require approvals (1 or more reviewers required before merge).
  • Require status checks to pass (CI, linters, security scans) before merging.
  • Require conversation resolution before merging (no unresolved review comments).
  • Do not allow force pushes to main.
  • Require linear history (optional) — enforce squash/rebase merges and prevent merge commits.
  • Restrict who can push to the branch (e.g., maintainers only) — useful for teams that want stricter control.

Configure these under Repository → Settings → Branches → Branch protection rules.

Merge strategies and guidance

  • Prefer Squash and merge for feature branches to keep main history concise (one commit per PR).
  • Use Merge commit when preserving branch topology is important (long-running branches, feature integration).
  • Fast-forward merges are fine for trivial single-commit branches but are less visible in history.

Example: force a non-fast-forward merge locally (create an explicit merge commit):

# make sure main is up to date
git checkout main
git pull origin main

# merge feature and create a merge commit
git merge --no-ff feat/your-feature
git push origin main

Hotfixes and rollback procedures

  • Hotfix workflow:

    1. Create a hotfix/<short-desc> branch from main.
    2. Make the urgent fix, run CI, open PR targeting main.
    3. After approval and merge, cherry-pick or merge the fix into the active development branch if needed.

  • Rollbacks:

    • If a merged change must be reverted, prefer creating a new revert PR (Revert "<original PR title>") rather than force-pushing history.

    • Use git revert <commit> to create a revert commit:

      git checkout main
git pull origin main
git revert <commit-hash>
git push origin main

    • For emergency rollbacks you may also create a hotfix branch that undoes the change and follow the hotfix workflow.

CODEOWNERS and reviewer routing

  • Add a CODEOWNERS file in the repository (root, docs/, or .github/) to automatically request reviewers for specific paths.
  • Syntax example (in CODEOWNERS):
# Backend team owns /api
/api/ @your-org/backend-team

# Docs owned by docs team
/docs/ @your-org/docs-team

This helps ensure the right people review changes to critical areas.

CI automation and security checks

  • Require automated tests and linters in your branch protection rules.
  • Add security scanners (Snyk, Dependabot, CodeQL) to detect vulnerabilities and require their checks to pass before merging.
  • Use CODEOWNERS + branch protections to auto-request reviews from the right owners.

Best-practice tips

  • Maintain CONTRIBUTING.md with repository rules (branch naming, PR size guidance, review expectations).
  • Add SECURITY.md for responsible disclosure instructions.
  • Keep protected branches minimal (usually only main, maybe release/*), and treat others as feature branches.
  • Use descriptive PR titles and detailed merge commit messages when needed.

Terminology explained

  • Branch Protection Rule: a set of rules configured in GitHub that applies to a specific branch (or branches) to enforce workflows.
  • Status Check: an external process (CI, test run) that reports status back to a PR.
  • Force Push: a Git command that overwrites the remote branch history; avoided on protected branches.