How to fix remote: error: GH006: Protected branch update failed - administrators cannot bypass in Git

First, verify the current branch protection configuration:

1. Go to your repository on GitHub
2. Click Settings > Branches
3. Find the branch protection rule for your target branch (e.g., main)
4. Click Edit to view the full settings

Look for these key settings:

✓ Require a pull request before merging
  ✓ Require approvals (1 or more)
✓ Require status checks to pass before merging
✓ Do not allow bypassing the above settings  <-- This is the key setting

If "Do not allow bypassing the above settings" is checked, administrators cannot push directly to this branch.

Note: Only repository admins can view and modify these settings. If you don't see the Settings tab, you may not have admin access.

Before attempting to bypass protections, consider why they were enabled:

Security reasons for enforcing admin restrictions:
- Prevents accidental pushes to production branches
- Ensures all code goes through review
- Creates audit trail for compliance (SOC 2, HIPAA, etc.)
- Protects against compromised admin accounts

If the restriction is intentional:

Follow the standard pull request workflow:

# Create a feature branch from main
git checkout main
git pull origin main
git checkout -b fix/urgent-hotfix

# Make your changes
git add .
git commit -m "Fix critical issue"

# Push the feature branch
git push -u origin fix/urgent-hotfix

# Open a pull request on GitHub
# Wait for required reviews and status checks
# Merge via the GitHub UI

This is the expected workflow when admin bypass is disabled. The restriction exists for good reason—embrace it rather than circumvent it.

If you're a repository admin and need to disable the restriction temporarily:

1. Go to Settings > Branches
2. Click Edit on the branch protection rule
3. Scroll to find "Do not allow bypassing the above settings"
4. Uncheck this option
5. Click Save changes

Now push your changes:

git push origin main

Critical: Re-enable the protection immediately after:

1. Return to Settings > Branches
2. Edit the rule and re-check "Do not allow bypassing the above settings"
3. Save changes

# Verify the push succeeded
git log origin/main --oneline -3

Warning: Leaving this setting disabled defeats the purpose of branch protection. Only disable temporarily for legitimate emergencies, and document why you did so.

GitHub's newer Repository rulesets feature provides more granular control over who can bypass protections:

1. Go to Settings > Rules > Rulesets
2. Click on the ruleset protecting your branch
3. Look for "Bypass list" section
4. Click Add bypass and select:
- Your username
- A team you belong to
- A GitHub App or deploy key

Bypass list:
  ✓ @your-username (Repository admin)
  ✓ @release-bot (Deploy key)

Note: Rulesets are the newer, more flexible replacement for branch protection rules. If your repository uses rulesets instead of branch protection rules, the bypass configuration lives here.

After adding yourself to the bypass list:

git push origin main

For GitHub Actions or CI/CD pipelines that need to push to protected branches, create a dedicated service account:

Step 1: Create a bot/service user account
- Create a new GitHub account specifically for automation
- Give it a descriptive name like your-org-bot

Step 2: Generate a Personal Access Token (PAT)
- Log in as the bot user
- Go to Settings > Developer settings > Personal access tokens > Tokens (classic)
- Generate a new token with repo scope
- Copy the token immediately (you won't see it again)

Step 3: Add the token as a repository secret
- In your repository, go to Settings > Secrets and variables > Actions
- Create a new secret: BOT_PAT with the token value

Step 4: Add the bot user to the bypass list
- Go to Settings > Branches or Settings > Rules > Rulesets
- Add the bot user to "Restrict who can push to matching branches" or the bypass list

Step 5: Update your GitHub Action

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.BOT_PAT }}

      - name: Configure Git
        run: |
          git config user.name "your-org-bot"
          git config user.email "[email protected]"

      - name: Push version bump
        run: |
          npm version patch
          git push origin main --follow-tags

Important: The default GITHUB_TOKEN cannot bypass branch protections even if the workflow has admin permissions. You must use a PAT from a user account in the bypass list.

If branch protection is enforced at the organization level, you may need help from an org admin:

Check for organization-level enforcement:

1. Ask your org admin to check Organization Settings > Repository > Repository rules
2. Look for rulesets that target your repository
3. Check if "Do not allow bypassing" is enforced at the org level

What an org admin can do:
- Modify org-level rulesets to allow bypass for specific users
- Add you to an exceptions team
- Temporarily disable the org-level rule
- Create a specific bypass for your repository

Provide context when requesting access:

Subject: Request for branch protection bypass access

Repository: org/repo-name
Branch: main
Reason: [Describe why you need direct push access]
Duration: [One-time / Temporary until DATE / Permanent]
Alternative considered: [What you tried before requesting this]

If your organization has strict compliance requirements, expect that the answer may be "no" and that you'll need to use the pull request workflow.

Even if you resolve the admin bypass issue, force pushes may still be separately restricted:

Check force push settings:

1. Go to Settings > Branches > Edit your branch protection rule
2. Look for "Allow force pushes" setting
3. Options are:
- Disabled (default)
- Everyone
- Specify who can force push

If you need to force push:

# First, try without force
git push origin main

# If that fails and force push is truly needed
git push --force-with-lease origin main

Why force push might be needed:
- Rebasing a branch to clean up history
- Removing sensitive data from commits
- Fixing a broken merge commit
- Amending a commit message

Safer alternative to force push:

# Instead of force pushing to main, create a new branch
git checkout -b main-fixed

# Push the fixed branch
git push origin main-fixed

# Open a PR to replace main with the fixed version
# This preserves history and allows review

Note: Force pushing to shared branches can cause problems for other developers. Consider if there's a non-destructive alternative.

If your GitHub Action is failing with this error, debug the authentication:

Check what token is being used:

- name: Debug token permissions
  run: |
    echo "Token type being used:"
    if [ -n "${{ secrets.BOT_PAT }}" ]; then
      echo "Using BOT_PAT"
    else
      echo "Using default GITHUB_TOKEN"
    fi

    # Check current user
    gh api user --jq '.login'
  env:
    GH_TOKEN: ${{ secrets.BOT_PAT || secrets.GITHUB_TOKEN }}

Common GitHub Actions authentication issues:

1. Using GITHUB_TOKEN instead of PAT:

# Wrong - GITHUB_TOKEN cannot bypass protections
   - uses: actions/checkout@v4

   # Correct - Use a PAT from bypass-enabled user
   - uses: actions/checkout@v4
     with:
       token: ${{ secrets.BOT_PAT }}

2. Token not configured for git operations:

- uses: actions/checkout@v4
     with:
       token: ${{ secrets.BOT_PAT }}
       persist-credentials: true  # Needed for subsequent git operations

3. Fine-grained PAT missing permissions:
- Ensure your fine-grained PAT has "Contents: Read and write" permission
- For classic PATs, ensure repo scope is selected

Verify token permissions:

# Test that your PAT has push access
curl -H "Authorization: token YOUR_PAT" \
  https://api.github.com/repos/OWNER/REPO