How to Configure Git Branch Protection Using setup-branch-protection.js in AIOS Core

The setup-branch-protection.js script automates GitHub branch protection by enforcing required status checks, pull request reviews, and linear history policies through the GitHub CLI.

AIOS Core includes a specialized utility that streamlines repository security configuration. The setup-branch-protection.js script in the SynkraAI/aios-core repository eliminates manual GitHub UI navigation by programmatically applying standardized protection rules to your main branch. When you configure Git branch protection using setup-branch-protection.js, you enforce CI/CD gates that require passing status checks and peer reviews before any code merges.

Prerequisites

Before executing the script, ensure your environment meets the following requirements:

• GitHub CLI (gh) installed and authenticated with gh auth login
• Administration rights on the target repository
• Node.js runtime available in your environment

Install the GitHub CLI using your package manager:

brew install gh  # macOS

gh auth login    # Select GitHub.com, HTTPS, and grant repo admin scope

Applying Branch Protection Rules

To enforce protection on the default branch (main or master), run the script from the repository root:

node scripts/setup-branch-protection.js

The script configures the following required status checks:

• ESLint
• TypeScript type-checking
• Jest tests
• Story-checkbox validation

It also establishes pull request review requirements including one approving review and dismissal of stale reviews when new commits are pushed. Additionally, the script enforces linear history (rebase-only), blocks force pushes, prevents branch deletion, and applies these rules to repository administrators.

Verifying Current Configuration

To inspect existing protection rules without modifying them, append the --status flag:

node scripts/setup-branch-protection.js --status

This queries the current configuration and displays the active rules in your terminal, showing the required status checks, review counts, and branch policies currently enforced on the default branch.

Customizing Protection Rules

The script builds a JSON payload defined in the PROTECTION_CONFIG object located around lines 20-40 of scripts/setup-branch-protection.js. To modify the protection rules:

1. Open scripts/setup-branch-protection.js in your editor
2. Locate the PROTECTION_CONFIG object
3. Adjust the required_status_checks.contexts array to add or remove status checks
4. Modify required_pull_request_reviews to change approval counts or stale review dismissal
5. Re-run the script to apply updates

How the Script Works Under the Hood

The CLI entry point ultimately invokes the protectBranch method of the BranchManager class. According to the SynkraAI/aios-core source code, this implementation resides in .aios-core/infrastructure/scripts/branch-manager.js at line 255, with a development-mode copy available at .aios-core/development/scripts/branch-manager.js (line 254).

The protectBranch method performs two operations:

1. Local persistence: Writes protection rules to .git/aios-branch-protection.json for offline tooling and quick reference
2. API integration: In the current implementation, this records the configuration locally; future releases will invoke the actual GitHub REST API directly

When you run setup-branch-protection.js, it constructs the protection payload and delegates to this manager, which would normally transmit the configuration to GitHub's branch protection API endpoints.

Summary

• The setup-branch-protection.js script automates GitHub branch protection configuration for AIOS Core repositories through the GitHub CLI
• It enforces four required status checks (ESLint, TypeScript, Jest, Story-checkbox), requires one PR approval, and mandates linear history
• Use the --status flag to verify current protection settings without applying changes
• Modify the PROTECTION_CONFIG object in the script to customize protection rules before execution
• The underlying BranchManager.protectBranch() method in .aios-core/infrastructure/scripts/branch-manager.js handles the core logic and local state management

Frequently Asked Questions

What prerequisites are required to run setup-branch-protection.js?

You must install the GitHub CLI (gh), authenticate with gh auth login using an account with repository admin rights, and have Node.js available. Without admin privileges, the script cannot modify branch protection settings.

How can I check the current branch protection status without making changes?

Run the script with the --status flag: node scripts/setup-branch-protection.js --status. This displays the current protection configuration including required status checks, review requirements, and branch policies without modifying the repository settings.

Can I customize which status checks are required by the script?

Yes. Edit the PROTECTION_CONFIG object in scripts/setup-branch-protection.js (approximately lines 20-40) to modify the required_status_checks.contexts array. Add or remove check names like "ESLint" or "Jest Tests", then re-run the script to apply your custom configuration.

Where does the script store the protection configuration locally?

The protectBranch method in .aios-core/infrastructure/scripts/branch-manager.js writes a local JSON representation to .git/aios-branch-protection.json. This file serves offline tooling and verification purposes, though the script is designed to eventually call the GitHub API directly in production environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}