Home / Guides / Branch Protection

Branch Protection

Branch protection rules enforce requirements before code can be merged. This ensures code quality by requiring reviews, passing builds, and preventing destructive operations.

Advanced

Overview

Branch protection is configured in .anvil/config.yml and enforced when:

A PR is created targeting a protected branch
A PR signature is added
A PR merge is requested
A force push is attempted

yaml

# .anvil/config.yml
branch_protection:
  main:
    required_signatures: 2
    block_force_pushes: true
    auto_merge: false
    build:
      enabled: true
      require_success: true
    ai_review:
      enabled: true

Required Signatures

Control how many approvals are needed before a PR can be merged.

Configuration

yaml

branch_protection:
  main:
    required_signatures: 2  # Need 2 approvals
  
  develop:
    required_signatures: 1  # Need 1 approval
  
  "*":
    required_signatures: 1  # Default: 1 approval

How Signatures Work

PR is created with a single squashed commit
Reviewers approve using anvil pr approve
Each approval adds a GPG-signed git note
Server counts signatures and updates is_mergeable status
When count ≥ required_signatures, PR becomes mergeable

👤 Who Can Approve?

Only repository members with write or admin roles can approve PRs. The PR author cannot approve their own PR.

Checking Signature Status

bash

anvil pr status abc1234

# Output:
# PR Status: Open
# Approvals: 1/2 required
# Mergeable: No (waiting for approvals)
# 
# Signatures:
#   ✓ alice@example.com approved at 2024-01-15 10:30 UTC

Force Push Protection

Prevent force pushes to important branches to protect commit history.

yaml

branch_protection:
  main:
    block_force_pushes: true  # Block force pushes
  
  develop:
    block_force_pushes: true
  
  "feature/*":
    block_force_pushes: false  # Allow on feature branches

⚠️ Force Push Blocked

When a force push is blocked, the server rejects the push with an error message. The user must use a normal push or merge instead.

Auto Merge

Automatically merge PRs when all requirements are met.

yaml

branch_protection:
  develop:
    required_signatures: 1
    auto_merge: true  # Auto-merge when approved
    build:
      enabled: true
      require_success: true

When Auto Merge Triggers

PR is automatically merged when all of these are true:

✅ Required signatures collected
✅ Build passed (if builds enabled)
✅ No active rejections
✅ Commit is signed

💡 Use Cases

Auto merge is useful for development branches where you want fast iteration. For production branches (main), keep it disabled for manual control.

Build Requirements

Require passing builds before PRs can be merged.

yaml

branch_protection:
  main:
    required_signatures: 2
    build:
      enabled: true           # Enable builds
      require_success: true   # Block merge if build fails
      timeout_seconds: 1800   # 30 minute timeout

Build Workflow

PR is created → Build job is created
Build agent picks up job → Executes pipeline
Build result stored as git note
PR status updated with build result
If require_success: true, merge blocked until build passes

Build Status in PR

bash

anvil pr status abc1234

# Output:
# PR Status: Open
# Build: SUCCESS ✓
# Approvals: 2/2 required
# Mergeable: Yes

See the Build Agents guide for setting up CI/CD.

Branch Patterns

Use patterns to apply rules to multiple branches.

Pattern Syntax

Pattern	Matches
`main`	Exact match: "main"
`feature/*`	"feature/" followed by anything (single level)
`feature/**`	"feature/" followed by anything (multi-level)
`*.hotfix`	Anything ending in ".hotfix"
`*`	Anything (default fallback)

Pattern Priority

More specific patterns take precedence:

yaml

branch_protection:
  # Most specific - exact match
  main:
    required_signatures: 2
  
  # Less specific - pattern match
  release/*:
    required_signatures: 2
  
  # Least specific - fallback
  "*":
    required_signatures: 1

Configuration Reference

All available branch protection options:

Option	Type	Default	Description
`required_signatures`	integer	`1`	Number of approvals required to merge
`block_force_pushes`	boolean	`true`	Block force pushes to this branch
`auto_merge`	boolean	`false`	Automatically merge when all approvals collected
`build.enabled`	boolean	`false`	Enable builds for this branch
`build.require_success`	boolean	`true`	Require successful build before merge
`build.timeout_seconds`	integer	`3600`	Build timeout in seconds
`ai_review.enabled`	boolean	`false`	Enable AI code review
`ai_review.provider`	string	`"zhipu"`	AI provider to use
`ai_review.model`	string	`"glm-4.7"`	AI model to use for review

For complete configuration options including pipeline definitions, see the Configuration Reference.

What's Next?

🤖 Build Agents

Set up CI/CD pipelines on your infrastructure.

🧠 AI Code Review

Enable automated AI-powered code reviews.

⚙️ Configuration

Full configuration file reference.