Fix 'fatal: remote error: You can't push to protected branch'

What this error means

You are pushing commits directly to a branch that the remote server has marked as protected (commonly main or master). Protection rules block direct pushes to enforce reviews, checks, or prevent force-pushes. The server rejects the push with a fatal remote error.

Typical platforms: GitHub, GitLab, Bitbucket, and self-hosted servers with pre-receive hooks.

Quickstart

• Create a new branch and push that instead.
• Open a Pull Request (PR) or Merge Request (MR) into the protected branch.
• If you must push directly (discouraged), have a maintainer adjust branch protection or grant you the required permission.

Minimal working example (push via a feature branch)

# 1) Confirm your current branch and remote
git status -sb
git remote -v

# 2) Create and switch to a new branch
BR="feature/fix-issue-123"
git switch -c "$BR"

# 3) Commit your work
# (Assumes you already changed files)
git add -A
git commit -m "Fix: address issue 123"

# 4) Push the new branch and set upstream
# This avoids pushing to protected main/master directly
git push -u origin HEAD

# 5) Open a PR/MR from $BR into main/master in your Git host UI

If your organization uses a different default branch (e.g., develop), target that branch in your PR/MR.

Diagnose before changing settings

1. Verify which branch you were trying to push.

git branch --show-current

1. Confirm the remote default branch and whether it exists.

git ls-remote --symref origin HEAD
# Shows remote default branch, e.g., refs/heads/main

git ls-remote --heads origin main master develop

1. Ensure you’re pushing to the intended remote.

git remote -v
# If wrong, set the correct remote URL
# git remote set-url origin <correct-url>

If you still need to push to the protected branch, check repository settings (you’ll need Maintainer/Admin permissions).

Common protection settings by platform

• GitHub:
  • Require a pull request before merging
  • Restrict who can push to matching branches
  • Require status checks to pass before merging
  • Allow force pushes (usually disabled) and Include administrators
• GitLab:
  • Protected branches with Allowed to push/merge roles
  • Code Owner approvals, status checks via CI
• Bitbucket:
  • Branch permissions: Prevent changes, Require pull request, Restrict push

Repository Settings → Branches/Branch protection is where you configure these.

Fix options

1. Preferred: Use a feature branch and PR/MR

   • Keeps main stable, enforces reviews and CI.
   • Steps:
     1. Create a branch: git switch -c feature/my-change
     2. Push it: git push -u origin HEAD
     3. Open a PR/MR into main/master.

2. If policy allows: Adjust protection rules

   • Temporarily relax protection (e.g., allow maintainers to push, remove "require PR"), push your change, then re-enable protections.
   • Safer alternative: Add yourself to the allowed push list for this branch.

3. Self-hosted hooks: Update pre-receive hooks

   • A pre-receive hook may reject pushes to main. Example hook logic:

#!/usr/bin/env bash
# pre-receive (server-side example): reject direct pushes to main
while read old new ref; do
  branch=${ref#refs/heads/}
  if [ "$branch" = "main" ]; then
    echo "Direct pushes to main are not allowed. Use a PR."
    exit 1
  fi
done
exit 0

• To allow certain roles/users, modify logic or integrate with your auth system. Test in a staging repo before applying globally.

1. Fork workflow
   • If you don’t have push rights, fork the repository, push to your fork, and open a PR from fork:branch to upstream:main.

Edge cases and checks

• You pushed to the wrong remote or repo: verify origin URL and organization.
• You pushed to main but intended develop: retarget your PR or cherry-pick to the correct branch.
• Required commit signing or linear history: amend or rebase locally, then push to your feature branch; the protection blocks merging, not your branch push.
• Tags may be protected separately: pushing a tag named after a protected pattern can fail similarly.

Pitfalls to avoid

• Force-pushing to protected branches: breaks history and CI pipelines; usually prohibited.
• Disabling protections permanently: creates long-term risk; prefer temporary changes with audit.
• Working long-lived feature branches without rebasing: increases merge conflicts; rebase or merge main regularly.
• Bypassing CI/status checks: undermines the purpose of the protection; fix the checks instead.

Performance notes

• Large pushes trigger server-side checks (hooks, CI). Keep commits focused and avoid pushing unnecessary binaries.
• Shallow clones (git clone --depth 1) speed local setup but may complicate rebases; use thoughtfully.
• Avoid pushing many refs at once: push only your branch (git push origin HEAD) to reduce server work.
• Pre-receive hooks can add latency; don’t retry rapidly—fix the root cause (branch protection) first.

Verification steps (after fix)

1. Push your feature branch without errors.

git push -u origin HEAD

1. Open a PR/MR; ensure required reviews and checks are green.

2. Merge via the platform UI; confirm your commits appear on the protected branch.

3. Update local default branch and prune merged branches.

git switch main
git pull --ff-only origin main
git branch -d feature/fix-issue-123

When you truly must push to the protected branch

• Coordinate with a maintainer to temporarily allow your push window.
• Use a single, auditable commit.
• Immediately re-enable protections and verify logs.

FAQ

• Q: Can I bypass protection with a force push if I’m admin?

  • A: Only if the rule includes "Include administrators" disabled or explicitly allows it. Most teams disallow this. Prefer PRs.

• Q: My push to a feature branch was rejected—why?

  • A: The repository may protect patterns (e.g., release/*) or restrict who can push any branch. Ask a maintainer to grant access.

• Q: Status checks fail; does that block push?

  • A: Usually it blocks merging, not pushing to your feature branch. It will block direct pushes to protected branches if "require PR" is enabled.

• Q: Can I automate PR creation?

  • A: Yes, via your platform’s CLI/API. Even then, avoid pushing directly to protected branches; have automation open PRs.