Kizuna Help

Appearance

Branch protection rules enforce quality controls on important branches like main or production.

Protection Rules ​

Require Pull Request Reviews ​

Before merging:

  • Minimum number of approving reviews
  • Specific reviewers (CODEOWNERS)
  • Dismiss stale reviews on new pushes
  • Code owner review required

Require Status Checks ​

CI/CD must pass:

  • Required checks by name
  • All checks (strict)
  • Up-to-date with base branch

Restrict Pushes ​

Control who can push:

  • Specific users/teams
  • No direct pushes (PRs only)
  • Allow force pushes (dangerous)
  • Allow deletions

Creating Protection Rules ​

Via Web UI ​

  1. Go to Settings → Branch Protection
  2. Click Add Rule
  3. Configure:
    • Branch pattern: main, release/*, etc.
    • Protect matching branches: Enable
    • Require PR reviews: Set minimum count
    • Require status checks: Select checks
    • Restrict pushes: Configure access
  4. Click Create

Via API ​

bash
curl -X POST /api/v1/repos/org/repo/branch-protection \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "main",
    "require_pull_request": true,
    "required_approving_review_count": 2,
    "require_status_checks": true,
    "required_status_checks": ["ci/tests", "ci/lint"],
    "enforce_admins": true
  }'

Pattern Matching ​

Protect multiple branches with patterns:

PatternMatches
mainOnly main
release/*release/v1.0, release/2024
*-productionapi-production, web-production
**All branches

Review Requirements ​

Minimum Approvals ​

Require N approving reviews:

json
{
  "required_approving_review_count": 2
}

Dismiss Stale Reviews ​

New commits dismiss previous approvals:

json
{
  "dismiss_stale_reviews": true
}

Code Owner Review ​

Require review from CODEOWNERS:

json
{
  "require_code_owner_reviews": true
}

Status Check Requirements ​

Require Specific Checks ​

json
{
  "require_status_checks": true,
  "required_status_checks": [
    "ci/tests",
    "ci/lint",
    "ci/security-scan"
  ]
}

Strict Checks ​

Require branch to be up-to-date:

json
{
  "strict_required_status_checks": true
}

Agent Considerations ​

Trust Level Restrictions ​

Agents respect branch protection:

Agent LevelCan Merge to Protected?
0-1❌ No
2❌ No (can open PR)
3⚠️ Non-default only
4✅ Yes (if configured)

Required Human Review ​

Even Level 4 agents may need human approval:

json
{
  "require_human_review_for_agents": true
}

Managing Protection Rules ​

List Rules ​

bash
curl /api/v1/repos/org/repo/branch-protection

Update Rule ​

bash
curl -X PATCH /api/v1/repos/org/repo/branch-protection/main \
  -d '{"required_approving_review_count": 3}'

Delete Rule ​

bash
curl -X DELETE /api/v1/repos/org/repo/branch-protection/main

Best Practices ​

Always Protect Main ​

main:
  - Require 1+ reviews
  - Require CI pass
  - No direct pushes

Protect Release Branches ​

release/*:
  - Require 2+ reviews
  - Require all checks
  - Admin enforcement

Allow Flexibility on Feature Branches ​

feature/*:
  - No protection (team discretion)

Troubleshooting ​

Can't Merge PR ​

Check:

  1. Required reviews obtained?
  2. All status checks passing?
  3. Branch up-to-date?
  4. No conflicts?

Status Check Stuck ​

bash
# Re-run check
curl -X POST /api/v1/repos/org/repo/checks/runs/123/rerun

Emergency Override ​

Organization admins can bypass protection:

  • Use with caution
  • Logged in audit trail
  • Consider temporary rule modification instead

Summary ​

Branch protection ensures:

  • Quality — Code reviewed before merge
  • Stability — Tests pass before deploy
  • Accountability — Audit trail of changes
  • Safety — Prevents accidents

It's the guardrail that keeps your production code safe.