Branch Protection

Branch protection rules prevent unauthorized changes to important branches like main or release/*.

Creating a Protection Rule

Navigate to Settings

Go to Repository Settings → Branches

Add Rule

Click Add Rule and configure:

Branch pattern: e.g., main, release/*, hotfix-*
Requirements: Select which checks must pass
Restrictions: Who can push directly

Protection Options

Pull Request Requirements

Setting	Description	Default
`requirePullRequest`	Require PR for all changes	`true`
`requiredApprovals`	Minimum approving reviews	`1`
`dismissStaleReviews`	Dismiss approvals when PR is updated	`false`
`requireCodeOwnerReview`	Require review from CODEOWNERS	`false`

Commit Requirements

Setting	Description	Default
`requireSignedCommits`	All commits must be GPG signed	`false`
`requireLinearHistory`	No merge commits allowed	`false`

Push Restrictions

Setting	Description	Default
`allowForcePush`	Allow `--force` push	`false`
`allowDeletions`	Allow branch deletion	`false`
`restrictPushUsers`	Only specific users can push	`[]`

Status Check Requirements

Setting	Description	Default
`requireStatusChecks`	Require passing CI checks	`false`
`requiredStatusChecks`	List of required check contexts	`[]`

Branch Patterns

Use glob patterns to match multiple branches:

Pattern	Matches
`main`	Only `main` branch
`release/*`	`release/1.0`, `release/2.0`, etc.
`feature/**`	Any branch under `feature/`
`hotfix-*`	`hotfix-123`, `hotfix-bug`, etc.

Required Status Checks

Status checks integrate with CI to block merges until tests pass:

{
  "requireStatusChecks": true,
  "requiredStatusChecks": ["ci/test", "ci/lint", "ci/build"]
}

CI Integration

When CI runs, it reports status to the branch protection system:

PR is created/updated
CI runs tests
Status check is reported (pending → success/failure)
Branch protection allows/blocks merge

Status Check States

State	Description	Blocks Merge?
`pending`	Check is running	Yes
`success`	Check passed	No
`failure`	Check failed	Yes
`error`	Check errored	Yes

CODEOWNERS Integration

When requireCodeOwnerReview is enabled:

CODEOWNERS file is parsed on PR creation
Owners are auto-assigned as reviewers
At least one owner must approve
Owner approval is required to merge

# CODEOWNERS file
* @team-lead
/src/api/** @backend-team
*.tsx @frontend-team

Bypass Permissions

Admins can configure bypass rules:

Permission	Can Bypass
Repository Admin	All rules
Org Owner	All rules
Configured Users	Specific rules

⚠️

Bypassing branch protection is logged in the audit trail.

API Reference

Get Protection Rules

GET /api/v1/code/repos/{org}/{repo}/branches/protection
 
# Response
{
  "rules": [
    {
      "id": "rule_xxx",
      "branchPattern": "main",
      "requirePullRequest": true,
      "requiredApprovals": 2,
      "requireStatusChecks": true,
      "requiredStatusChecks": ["ci/test"]
    }
  ]
}

Create Protection Rule

POST /api/v1/code/repos/{org}/{repo}/branches/protection
Content-Type: application/json
 
{
  "branchPattern": "main",
  "requirePullRequest": true,
  "requiredApprovals": 2,
  "dismissStaleReviews": true,
  "requireCodeOwnerReview": true,
  "requireStatusChecks": true,
  "requiredStatusChecks": ["ci/test", "ci/lint"],
  "requireSignedCommits": false,
  "allowForcePush": false,
  "allowDeletions": false
}

Update Protection Rule

PATCH /api/v1/code/repos/{org}/{repo}/branches/protection/{ruleId}
Content-Type: application/json
 
{
  "requiredApprovals": 3
}

Delete Protection Rule

DELETE /api/v1/code/repos/{org}/{repo}/branches/protection/{ruleId}

Best Practices

For Main Branch

{
  "branchPattern": "main",
  "requirePullRequest": true,
  "requiredApprovals": 2,
  "dismissStaleReviews": true,
  "requireCodeOwnerReview": true,
  "requireStatusChecks": true,
  "requiredStatusChecks": ["ci/test", "ci/lint", "ci/build"],
  "allowForcePush": false,
  "allowDeletions": false
}

For Release Branches

{
  "branchPattern": "release/*",
  "requirePullRequest": true,
  "requiredApprovals": 1,
  "requireSignedCommits": true,
  "allowForcePush": false,
  "allowDeletions": false
}

For Feature Branches

Feature branches typically don't need protection rules, but you can add lightweight rules:

{
  "branchPattern": "feature/**",
  "requirePullRequest": false,
  "allowForcePush": true,
  "allowDeletions": true
}

Plan Limits

Plan	Protection Features
Free	Basic (require PR, approvals)
Pro	Advanced (status checks, CODEOWNERS)
Enterprise	Full (signed commits, restrict users)

AI Code Review Webhooks