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

> Automate GitHub branch protection in aios-core using setup-branch-protection.js. Enforce required checks reviews and linear history with the GitHub CLI.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The [`setup-branch-protection.js`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/SynkraAI/aios-core/blob/main/scripts/setup-branch-protection.js). To modify the protection rules:

1. Open [`scripts/setup-branch-protection.js`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/branch-manager.js) at line 255, with a development-mode copy available at [`.aios-core/development/scripts/branch-manager.js`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/branch-manager.js) writes a local JSON representation to [`.git/aios-branch-protection.json`](https://github.com/SynkraAI/aios-core/blob/main/.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.