How to fix remote: Branch restrictions prevented the push in Git

GitBEGINNERMEDIUMUpdated Dec 6, 2025· 231 views

This error occurs when Bitbucket's branch protection rules block your push attempt. The repository has restrictions configured that require either specific user permissions, pull requests, or signed commits before changes can be pushed to the protected branch.

Quick fix

Fixes remote: Branch restrictions prevented the push

# Create a feature branch from your current work
git checkout -b feature/your-changes

# Push the feature branch (not protected)
git push -u origin feature/your-changes
  1. Use a pull request instead of pushing directly
  2. Verify your user is in the write access list
  3. Move SSH key to personal account settings
  4. Use HTTPS with app password instead of access tokens
git — error
# Create a feature branch from your current work
git checkout -b feature/your-changes
# Push the feature branch (not protected)
git push -u origin feature/your-changes
remote: Branch restrictions prevented the push

What this error means

When you push to a Bitbucket repository and receive the "Branch restrictions prevented the push" error (often accompanied by "pre-receive hook declined"), it means the target branch has protection rules that your push doesn't satisfy. Bitbucket's branch restrictions are a security feature designed to: - Enforce code review through mandatory pull requests - Prevent accidental direct commits to important branches like main or master - Restrict who can modify specific branches - Block force pushes that could rewrite history - Require signed commits for compliance This error is Bitbucket doing exactly what it's configured to do—protecting your codebase from unauthorized or unchecked changes. The restriction is enforced server-side via a pre-receive hook, which validates all incoming pushes before accepting them. This commonly occurs when: - Developers try to push directly to a protected branch instead of using a pull request - SSH keys are added at the workspace level instead of personal account level - Access tokens are used instead of personal credentials (unsupported with branch restrictions) - CI/CD pipelines lack the proper authentication to bypass restrictions

Typical symptoms

  • Git push fails with 'remote: Branch restrictions prevented the push' message
  • Error shows '[remote rejected] main -> main (pre-receive hook declined)'
  • Push fails with 'error: failed to push some refs to bitbucket.org'
  • Force push attempts are rejected with 'Permission denied to force push branch'
  • CI/CD pipeline fails during push step to protected branches
  • Push worked previously but now fails after branch restrictions were enabled
  • Error message mentions 'permission denied to update branch'

Common causes

  1. User account is not in the branch restrictions write access list (most common)
  2. Attempting to push directly to a protected branch that requires pull requests
  3. Using workspace or repository SSH keys instead of personal account SSH keys
  4. Using access tokens which are not supported with branch restrictions (Bitbucket limitation)
  5. Force push attempted on a branch with 'Prevent rewriting history' enabled
  6. Repository has reached Bitbucket's 2 GB size limit (becomes read-only)
  7. Commits are not GPG-signed when signature enforcement is enabled (Premium feature)
  8. Branch creation restrictions block creating new branches matching a pattern

How to fix "remote: Branch restrictions prevented the push"

1Use a pull request instead of pushing directly

The intended workflow for protected branches is to use pull requests:

bash
# Create a feature branch from your current work
git checkout -b feature/your-changes

# Push the feature branch (not protected)
git push -u origin feature/your-changes

Then create a pull request in Bitbucket:
1. Go to your repository in Bitbucket
2. Click Create pull request
3. Select your feature branch as source and the protected branch as destination
4. Add reviewers and submit for review

This is the recommended approach as it enables code review and maintains branch protection.

2Verify your user is in the write access list

If you need direct push access, check your permissions:

1. Go to your repository in Bitbucket
2. Navigate to Repository settings > Branch restrictions
3. Find the rule affecting your target branch
4. Click Edit and check the "Write access" section

To add write access:
- Under "Only specific people or groups have write access"
- Add your username or a group you belong to
- Click Save

Note: Only repository admins can modify branch restriction settings.

3Move SSH key to personal account settings

Branch restrictions require user identification. Workspace-level SSH keys don't provide this:

Check where your SSH key is configured:
1. Personal Settings > SSH keys (correct location)
2. Workspace Settings > SSH keys (will cause this error)
3. Repository Settings > Access keys (will cause this error)

To fix:
1. Go to Personal Bitbucket settings (click your avatar > Personal settings)
2. Navigate to SSH keys
3. Add your public SSH key here
4. Remove the same key from workspace or repository settings

bash
# Display your public key to copy
cat ~/.ssh/id_ed25519.pub
# or
cat ~/.ssh/id_rsa.pub

Retry the push after moving the key.

4Use HTTPS with app password instead of access tokens

Access tokens don't work with branch restrictions. Use an app password instead:

1. Go to Personal Bitbucket settings > App passwords
2. Click Create app password
3. Give it a name and select required permissions (at minimum: Repositories - Write)
4. Copy the generated password

Update your remote URL to use HTTPS:

bash
# Check current remote
git remote -v

# Change to HTTPS with your username
git remote set-url origin https://yourusername@bitbucket.org/workspace/repository.git

# Push (you'll be prompted for the app password)
git push origin main

For persistent storage, configure Git credential helper:

bash
git config --global credential.helper store
5Enable history rewriting for rebases

If you're trying to force push after a rebase and getting permission denied:

1. Go to Repository settings > Branch restrictions
2. Find and edit the rule for your branch
3. Enable Allow rewriting branch history
4. Save the changes

bash
# Now force push should work
git push --force-with-lease origin main

Warning: Only enable this if your workflow requires rebasing. Force pushing can overwrite others' work if not done carefully. Using --force-with-lease is safer than --force.

6Check repository size limit

Bitbucket Cloud has a 2 GB repository size limit. If exceeded, the repo becomes read-only:

Check your repository size:
1. Go to Repository settings > Repository details
2. Look for the repository size

If over limit:
1. Use BFG Repo-Cleaner or git filter-branch to remove large files
2. Consider using Git LFS for large assets

bash
# Install BFG (requires Java)
# Download from https://rtyley.github.io/bfg-repo-cleaner/

# Remove files larger than 100MB
java -jar bfg.jar --strip-blobs-bigger-than 100M your-repo.git

# Clean up and force push
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force

Contact Atlassian support if you need temporary write access to clean up.

7Configure CI/CD with proper authentication

For Bitbucket Pipelines or other CI systems:

Using Bitbucket Pipelines (built-in):

Pipelines automatically get authenticated, but branch restrictions may still apply. Use the clone step with a user that has bypass permissions:

yaml
pipelines:
  default:
    - step:
        name: Build and Push
        script:
          - git config user.email "ci@yourcompany.com"
          - git config user.name "CI Bot"
          - git push origin main

For external CI (Jenkins, GitHub Actions, etc.):

1. Create a dedicated "bot" user account in Bitbucket
2. Add this user to the branch restrictions write access list
3. Generate an app password for this user
4. Use HTTPS authentication with these credentials in your CI

bash
# In CI environment
git remote set-url origin https://botuser:${BITBUCKET_APP_PASSWORD}@bitbucket.org/workspace/repo.git
git push origin main

Advanced notes

### Access Token Limitation (BCLOUD-22400)

As of 2024, Bitbucket Cloud does not support using repository, project, or workspace access tokens when branch restrictions are configured. This is a known limitation tracked in feature request BCLOUD-22400. The workaround is to use app passwords tied to a user account that has branch restriction bypass permissions.

### Branch Restriction Types in Bitbucket

Bitbucket offers several restriction types:
- Prevent all changes: Blocks all pushes and duplicate branch creation
- Prevent branch creation: Stops new branches matching the pattern
- Prevent deletion: Restricts branch and tag deletion
- Prevent rewriting history: Blocks force pushes and rebases
- Prevent changes without a pull request: Enforces PR-only workflow

### Project vs Repository Level Restrictions

Branch restrictions can be applied at two levels:
- Project-wide: Affects all repositories in the project (Bitbucket Data Center/Server)
- Repository-specific: Creates additional restrictions for individual repositories

Repository-level restrictions add to project-level restrictions; they don't override them.

### Bitbucket Cloud vs Data Center/Server

The error messages and settings locations differ slightly:
- Cloud: Repository settings > Branch restrictions
- Data Center/Server: Repository settings > Branch permissions (under "Workflow")

### Merge Checks vs Branch Restrictions

Don't confuse these two features:
- Branch restrictions: Control who can push and what actions are allowed
- Merge checks: Control conditions for merging pull requests (required approvals, passing builds)

Both can prevent changes, but they're configured separately.

### GPG Commit Signing (Premium Feature)

Bitbucket Premium allows requiring signed commits. If enabled and you push unsigned commits:
1. Set up GPG signing locally
2. Configure Git to sign commits: git config commit.gpgsign true
3. Ensure your GPG key is added to your Bitbucket account

Frequently asked questions

What does "remote: Branch restrictions prevented the push" mean?
When you push to a Bitbucket repository and receive the "Branch restrictions prevented the push" error (often accompanied by "pre-receive hook declined"), it means the target branch has protection rules that your push doesn't satisfy. Bitbucket's branch restrictions are a security feature designed to: - Enforce code review through mandatory pull requests - Prevent accidental direct commits to important branches like main or master - Restrict who can modify specific branches - Block force pushes that could rewrite history - Require signed commits for compliance This error is Bitbucket doing exactly what it's configured to do—protecting your codebase from unauthorized or unchecked changes. The restriction is enforced server-side via a pre-receive hook, which validates all incoming pushes before accepting them.
How do I fix "remote: Branch restrictions prevented the push"?
This error occurs when Bitbucket's branch protection rules block your push attempt. The repository has restrictions configured that require either specific user permissions, pull requests, or signed commits before changes can be pushed to the protected branch.
What causes "remote: Branch restrictions prevented the push"?
User account is not in the branch restrictions write access list (most common) Attempting to push directly to a protected branch that requires pull requests Using workspace or repository SSH keys instead of personal account SSH keys
Is the "remote: Branch restrictions prevented the push" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading