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

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

# 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.

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.

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

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

Retry the push after moving the key.

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:

# Check current remote
git remote -v

# Change to HTTPS with your username
git remote set-url origin https://[email protected]/workspace/repository.git

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

For persistent storage, configure Git credential helper:

git config --global credential.helper store

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

# 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.

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

# 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.

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:

pipelines:
  default:
    - step:
        name: Build and Push
        script:
          - git config user.email "[email protected]"
          - 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

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