branch-protection

name	branch-protection
description	Diagnose and apply branch protection rules across a fleet. The standard pattern: require PR review, dismiss stale reviews, restrict who can push. Common issue: "Bypassed rule violations for refs/heads/main" — this happens when direct push is used despite protection. Use when CI builds keep failing on push branches that the user didn't intend to push to directly.

Branch Protection

When a repo has branch protection on main/master, you can't push directly. The user gets the "Bypassed rule violations" message. This skill covers the standard patterns and how to handle them.

Diagnose

gh api repos/camster91/<repo>/branches/main/protection

Returns:

{
  "required_pull_request_reviews": {
    "required_approving_review_count": 1
  },
  "required_signatures": {
    "enabled": false
  },
  "enforce_admins": {
    "enabled": false
  }
}

The "Bypassed Rule Violations" Gotcha

When you do git push origin main despite branch protection, the response is:

remote: Bypassed rule violations for refs/heads/main:
remote: - Changes must be made through a pull request.

This is a false alarm — the push actually succeeds. The "Bypassed" message is GitHub telling you that you bypassed the rule (not that you failed).

To verify the push went through:

git log --oneline -3 origin/main
# Should show your new commit at HEAD

Three Workflow Shapes

1. Direct push (works despite the message)

git push origin main
# "Bypassed" warning appears, push succeeds

Use this when:

• You're the only maintainer
• The user is OK with direct-to-main pushes
• The change is small and verified locally

2. Force push (works if you have the rights)

git push origin main --force-with-lease

Use when:

• A previous push was already there and you need to overwrite
• The lockfile or workflow file has gone out of sync due to branch-protection rebases

3. Branch + PR (cleanest for team workflows)

git checkout -b chore/my-fix
git push origin chore/my-fix
gh pr create --title "chore: my fix" --body "..."

Use when:

• The repo has multiple maintainers
• The user prefers PR-based workflows
• The change is large enough to warrant review

Common Error: "Bypassed rule violations" but Push Rejected

If the push actually fails (not just a warning), check:

# Is the branch correct?
git branch --show-current

# Is the remote correct?
git remote -v

# Does your local branch have the latest from origin?
git fetch origin
git status

Applying Branch Protection Fleet-Wide

# Require 1 approving review
for repo in <list>; do
    gh api -X PUT /repos/camster91/$repo/branches/main/protection \
        -H "Accept: application/vnd.github+json" \
        -d '{"required_pull_request_reviews":{"required_approving_review_count":1},"enforce_admins":null}' \
        2>&1 | head -3
done

Common pattern: required_approving_review_count: 1 with enforce_admins: null (admins can still push directly, but reviewers are required for everyone else).

Common Pitfalls

1. "Bypassed" doesn't mean "failed" — always verify with git log on origin
2. enforce_admins: false means admins bypass rules — if you want strict enforcement, set enforce_admins: true
3. Branch protection requires write access — if you get 403, the GitHub token doesn't have admin rights on the repo
4. The force_with_lease flag is safer than force — it checks if the remote changed before overwriting

Related Skills & Chains

• lockfile-regen — Often paired with branch-protection issues when you need to force-push a regenerated lockfile
• prisma-fleet-migration — The Prisma 7 migration may require a force-push on branch-protected repos