Branch Protection

Branch protection rules enforce quality and security gates on your most important branches. They prevent force pushes, require reviews before merging, and ensure that CI passes before code reaches production.

Creating Rules

drok branch-protection set main \
  --required-approvals 2 \
  --dismiss-stale-approvals \
  --require-status-checks "build,test,lint" \
  --require-signed-commits \
  --restrict-push-to @your-org/leads \
  --prevent-force-push \
  --prevent-deletion

Or configure through the web interface: Repository Settings > Branches > Add Rule.

Available Rules

Review Requirements

Rule	Description
`--required-approvals N`	Require N approving reviews before merge
`--dismiss-stale-approvals`	Dismiss approvals when new commits are pushed
`--require-review-from-codeowners`	Require approval from CODEOWNERS matches
`--require-review-from-teams T1,T2`	Require approval from specific teams

Status Check Requirements

Rule	Description
`--require-status-checks C1,C2`	Require named checks to pass before merge
`--require-all-status-checks`	Require all status checks to pass (not just named ones)
`--strict-status-checks`	Require status checks to be current (no stale results)

Push Restrictions

Rule	Description
`--restrict-push-to U1,T1`	Only specified users/teams can push directly
`--prevent-force-push`	Forbid force push to this branch
`--prevent-deletion`	Forbid branch deletion
`--require-linear-history`	Forbid merge commits (rebase only)

Signature Requirements

Rule	Description
`--require-signed-commits`	Require GPG or SSH signature on all commits
`--require-pq-signed-commits`	Require post-quantum signatures

Pattern-Based Rules

Apply rules to multiple branches using patterns:

drok branch-protection set "release/*" \
  --required-approvals 3 \
  --require-status-checks "build,test,security-scan" \
  --prevent-force-push \
  --prevent-deletion

Pattern syntax:

Pattern	Matches
`main`	Exactly the `main` branch
`release/*`	`release/1.0`, `release/2.0`, etc.
`feature/**`	`feature/auth`, `feature/auth/oauth`, etc.
`*`	All branches

Bypass Permissions

Organization owners and repository admins can be granted bypass permissions:

drok branch-protection set main \
  --bypass-actors @alice,@your-org/leads \
  --bypass-requires-merge-request

Bypass actors can push directly to protected branches but are still required to create merge requests (configurable). All bypass actions are recorded in the audit log.

Status Check Integration

Branch protection integrates with Drok Pipelines:

# .lehub/pipeline.yml
stages:
  - name: build
    steps:
      - name: Compile
        run: cargo build --release
  - name: test
    steps:
      - name: Unit tests
        run: cargo test
  - name: lint
    steps:
      - name: Clippy
        run: cargo clippy -- -D warnings

When --require-status-checks "build,test,lint" is configured, all three pipeline stages must pass before a merge request targeting the protected branch can be merged.

External Status Checks

External CI systems can report status checks via the API:

curl -X POST https://drok.us/api/v1/repos/org/repo/statuses/{sha} \
  -H "Authorization: Bearer $Drok_TOKEN" \
  -d '{
    "state": "success",
    "context": "external-ci",
    "description": "All tests passed",
    "target_url": "https://ci.example.com/build/123"
  }'

Viewing Rules

# List all branch protection rules
drok branch-protection list my-org/my-repo
 
# Show rules for a specific branch
drok branch-protection show my-org/my-repo main

Audit

All branch protection changes are logged in the organization audit log:

drok audit-log my-org --action "security.branch_protection_change"