Branch Protection Setup

Intermediate10 min

Configure branch protection rules to enforce code review, status checks, and merge requirements on important branches.

Prerequisites

-GitHub CLI (gh) installed and authenticated
-Repository admin access

Steps

View current branch protection rules

Check what protection rules are currently set on a branch.

$ gh api repos/{owner}/{repo}/branches/main/protection --jq '{requiredReviews: .required_pull_request_reviews.required_approving_review_count, statusChecks: .required_status_checks.contexts, enforceAdmins: .enforce_admins.enabled}'

Enable required pull request reviews

Require at least one approval before merging to main.

$ gh api -X PUT repos/{owner}/{repo}/branches/main/protection -f required_pull_request_reviews[required_approving_review_count]=1 -F enforce_admins=true -f required_status_checks[strict]=true -f required_status_checks[contexts][]='ci/test'

This applies to everyone including admins when enforce_admins is true.

Require status checks to pass

Ensure CI checks pass before a PR can be merged.

$ gh api -X PUT repos/{owner}/{repo}/branches/main/protection/required_status_checks -f strict=true -f contexts[]='ci/test' -f contexts[]='ci/lint'

Set strict=true to require the branch to be up-to-date with the base branch before merging.

View rulesets (newer alternative)

List repository rulesets which provide more flexible branch protection.

$ gh api repos/{owner}/{repo}/rulesets --jq '.[] | {name, enforcement, target: .conditions.ref_name}'

Full Script

full-script.sh

#!/bin/bash
# Branch Protection Setup
set -euo pipefail

REPO=${1:?"Usage: $0 <owner/repo>"}
BRANCH=${2:-"main"}

echo "=== Current Protection for $BRANCH ==="
gh api "repos/$REPO/branches/$BRANCH/protection" 2>/dev/null | jq '{
  required_reviews: .required_pull_request_reviews.required_approving_review_count,
  dismiss_stale_reviews: .required_pull_request_reviews.dismiss_stale_reviews,
  status_checks: .required_status_checks.contexts,
  enforce_admins: .enforce_admins.enabled,
  linear_history: .required_linear_history.enabled
}' || echo "No branch protection configured"

echo ""
echo "=== Rulesets ==="
gh api "repos/$REPO/rulesets" --jq '.[] | .name + " (" + .enforcement + ")"' 2>/dev/null || echo "No rulesets configured"

echo ""
echo "=== Protection Commands ==="
echo "View:   gh api repos/$REPO/branches/$BRANCH/protection"
echo "Delete: gh api -X DELETE repos/$REPO/branches/$BRANCH/protection"

FAQ

Discussion

Loading comments...

#!/bin/bash # Branch Protection Setup set -euo pipefail REPO=${1:?"Usage: $0 <owner/repo>"} BRANCH=${2:-"main"} echo "=== Current Protection for $BRANCH ===" gh api "repos/$REPO/branches/$BRANCH/protection" 2>/dev/null | jq '{ required_reviews: .required_pull_request_reviews.required_approving_review_count, dismiss_stale_reviews: .required_pull_request_reviews.dismiss_stale_reviews, status_checks: .required_status_checks.contexts, enforce_admins: .enforce_admins.enabled, linear_history: .required_linear_history.enabled }' || echo "No branch protection configured" echo "" echo "=== Rulesets ===" gh api "repos/$REPO/rulesets" --jq '.[] | .name + " (" + .enforcement + ")"' 2>/dev/null || echo "No rulesets configured" echo "" echo "=== Protection Commands ===" echo "View: gh api repos/$REPO/branches/$BRANCH/protection" echo "Delete: gh api -X DELETE repos/$REPO/branches/$BRANCH/protection"