From 4c796751b53fa95ae43f9dd928dc2b7d1db53a6a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 25 Jan 2026 14:18:21 +0000 Subject: [PATCH 1/2] Initial plan From f96c21c5040cf3725ed6b55553432f4608bb12dc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 25 Jan 2026 14:20:23 +0000 Subject: [PATCH 2/2] Add branch protection rules documentation Co-authored-by: shyamsridhar123 <117464342+shyamsridhar123@users.noreply.github.com> --- docs/BRANCH-PROTECTION.md | 252 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/BRANCH-PROTECTION.md diff --git a/docs/BRANCH-PROTECTION.md b/docs/BRANCH-PROTECTION.md new file mode 100644 index 0000000..9f57409 --- /dev/null +++ b/docs/BRANCH-PROTECTION.md @@ -0,0 +1,252 @@ +# Branch Protection Rules + +> *"Order through protection. Structure through rules."* + +This document outlines the recommended branch protection rules for the Agent Smith repository to ensure code quality, security, and collaboration best practices. + +--- + +## Overview + +Branch protection rules help enforce workflows and prevent accidental or unauthorized changes to important branches. For Agent Smith, we recommend protecting the `main` branch with the following settings. + +--- + +## Recommended Rules for `main` Branch + +### 1. Require Pull Request Reviews + +| Setting | Recommended Value | +|---------|-------------------| +| **Require a pull request before merging** | ✅ Enabled | +| **Required approving reviews** | 1 (minimum) | +| **Dismiss stale pull request approvals when new commits are pushed** | ✅ Enabled | +| **Require review from code owners** | ✅ Enabled (if CODEOWNERS file exists) | +| **Require approval of the most recent reviewable push** | ✅ Enabled | + +**Why:** Ensures all changes are reviewed by at least one other developer before being merged, catching bugs and maintaining code quality. + +### 2. Require Status Checks + +| Setting | Recommended Value | +|---------|-------------------| +| **Require status checks to pass before merging** | ✅ Enabled | +| **Require branches to be up to date before merging** | ✅ Enabled | + +**Required status checks:** +- `build` — Ensures the project compiles successfully +- `lint` — Verifies code style and formatting +- `test` — Runs the test suite + +**Why:** Prevents broken code from being merged into the main branch. + +### 3. Require Conversation Resolution + +| Setting | Recommended Value | +|---------|-------------------| +| **Require conversation resolution before merging** | ✅ Enabled | + +**Why:** Ensures all review comments are addressed before merging. + +### 4. Require Signed Commits + +| Setting | Recommended Value | +|---------|-------------------| +| **Require signed commits** | ⚡ Optional (Recommended for high-security environments) | + +**Why:** Verifies the identity of contributors and prevents commit spoofing. + +### 5. Require Linear History + +| Setting | Recommended Value | +|---------|-------------------| +| **Require linear history** | ✅ Enabled | + +**Why:** Maintains a clean, readable commit history by requiring squash or rebase merges. + +### 6. Restrict Push Access + +| Setting | Recommended Value | +|---------|-------------------| +| **Restrict who can push to matching branches** | ✅ Enabled | +| **Allow force pushes** | ❌ Disabled | +| **Allow deletions** | ❌ Disabled | + +**Why:** Prevents accidental force pushes or branch deletions that could destroy history. + +### 7. Lock Branch (Optional) + +| Setting | Recommended Value | +|---------|-------------------| +| **Lock branch** | ❌ Disabled (unless in maintenance mode) | + +**Why:** Only enable when the branch should be completely read-only. + +--- + +## How to Configure + +### Via GitHub Web UI + +1. Navigate to your repository on GitHub +2. Go to **Settings** → **Branches** +3. Under "Branch protection rules", click **Add rule** +4. Enter `main` as the branch name pattern +5. Configure the settings as recommended above +6. Click **Create** or **Save changes** + +### Via GitHub CLI + +```bash +# Create branch protection rule for main branch +gh api repos/{owner}/{repo}/branches/main/protection \ + --method PUT \ + --field required_status_checks='{"strict":true,"contexts":["build","lint","test"]}' \ + --field enforce_admins=true \ + --field required_pull_request_reviews='{"dismiss_stale_reviews":true,"require_code_owner_reviews":true,"required_approving_review_count":1}' \ + --field restrictions=null \ + --field required_linear_history=true \ + --field allow_force_pushes=false \ + --field allow_deletions=false +``` + +### Via Terraform (Infrastructure as Code) + +```hcl +resource "github_branch_protection" "main" { + repository_id = github_repository.agentsmith.node_id + pattern = "main" + + required_status_checks { + strict = true + contexts = ["build", "lint", "test"] + } + + required_pull_request_reviews { + dismiss_stale_reviews = true + require_code_owner_reviews = true + required_approving_review_count = 1 + } + + enforce_admins = true + require_signed_commits = false + required_linear_history = true + allow_force_pushes = false + allow_deletions = false +} +``` + +--- + +## Additional Recommendations + +### CODEOWNERS File + +Create a `.github/CODEOWNERS` file to automatically assign reviewers: + +``` +# Default owners for everything in the repo +* @shyamsridhar123 + +# Specific ownership for core source files +/src/ @shyamsridhar123 +/bin/ @shyamsridhar123 + +# Documentation +/docs/ @shyamsridhar123 +*.md @shyamsridhar123 +``` + +### Protected Tags + +Consider protecting release tags to prevent accidental deletion: + +```bash +# Protect tags matching v* pattern +gh api repos/{owner}/{repo}/rulesets \ + --method POST \ + --field name="Protect release tags" \ + --field target="tag" \ + --field enforcement="active" \ + --field conditions='{"ref_name":{"include":["refs/tags/v*"],"exclude":[]}}' +``` + +### Branch Naming Conventions + +Enforce branch naming conventions through rulesets: + +| Pattern | Purpose | +|---------|---------| +| `feature/*` | New features | +| `fix/*` | Bug fixes | +| `docs/*` | Documentation updates | +| `refactor/*` | Code refactoring | +| `chore/*` | Maintenance tasks | +| `release/*` | Release preparation | + +--- + +## Security Considerations + +### For Public Repositories + +- **Require status checks** to prevent malicious PRs from being merged +- **Dismiss stale reviews** to ensure new commits are reviewed +- **Disable force pushes** to maintain audit trail + +### For Private Repositories with Multiple Contributors + +- **Require code owner reviews** for sensitive files +- **Enable signed commits** for verified contributor identity +- **Restrict push access** to maintainers only + +--- + +## Troubleshooting + +### "Status check is required but not found" + +Ensure your CI workflow jobs have matching names: + +```yaml +# .github/workflows/ci.yml +jobs: + build: # This name must match the required status check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: npm run build +``` + +### "Branch is out of date" + +When "Require branches to be up to date before merging" is enabled: + +```bash +# Update your branch with main +git fetch origin +git rebase origin/main +# or +git merge origin/main +``` + +### "Require approving reviews" blocking admins + +If admins should bypass rules: + +1. Disable **"Do not allow bypassing the above settings"** +2. Or add admin to the bypass list in repository rulesets + +--- + +## References + +- [GitHub Docs: Managing a branch protection rule](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule) +- [GitHub Docs: About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) +- [GitHub Docs: About rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) + +--- + +> *"Structure protects. Rules enable freedom within boundaries."* +> +> *— The Architect*