How to fix remote: error: GH006: Protected branch update failed for refs/heads/main in Git

The standard solution is to use a pull request workflow:

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

# Make your changes and commit
git add .
git commit -m "Your changes"

# Push the feature branch
git push -u origin feature/your-changes

Then create a pull request on GitHub to merge your changes into the protected branch. This allows code review and CI checks to run.

If you have admin access, review the protection rules:

1. Go to your repository on GitHub
2. Navigate to Settings > Branches
3. Under "Branch protection rules", find your branch (e.g., main)
4. Click Edit to review current protections

Common protections that block direct pushes:
- "Require a pull request before merging"
- "Require status checks to pass before merging"
- "Require approvals"
- "Do not allow bypassing the above settings"

If certain users need direct push access (use sparingly):

1. Go to Settings > Branches > Edit your branch rule
2. Find "Allow specified actors to bypass required pull requests"
3. Add the user or team that needs bypass access
4. Click Save changes

Warning: This reduces protection. Only grant bypass access when absolutely necessary, and prefer the pull request workflow.

For GitHub Actions that need to push (like version bumps):

Option 1: Use a Personal Access Token (PAT)

1. Create a PAT with repo scope at GitHub Settings > Developer settings > Personal access tokens
2. Add it as a repository secret (e.g., BUILD_PAT)
3. Update your workflow:

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.BUILD_PAT }}

Option 2: Add a deploy key with write access

1. Generate an SSH key: ssh-keygen -t ed25519 -C "deploy-key"
2. Add the public key as a deploy key in repo Settings > Deploy keys (check "Allow write access")
3. Add the private key as a secret and configure checkout to use it

For robust CI/CD setups, create a dedicated GitHub user:

1. Create a new GitHub account for your build system
2. Generate a PAT for this account with repo permissions
3. Add this user to "Allow specified actors to bypass" in branch protection
4. Add the PAT as a secret in your repository
5. Update workflows to use this token:

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.MACHINE_USER_PAT }}

- name: Push changes
  run: |
    git config user.name "build-bot"
    git config user.email "[email protected]"
    git push origin main

GitHub Rulesets offer more flexible bypass options:

1. Go to Settings > Rules > Rulesets
2. Create a new ruleset or edit existing one
3. Under "Bypass list", add actors who can bypass:
- Select "Repository admin" or specific teams
- Add GitHub Apps or deploy keys

Rulesets allow you to:
- Set different rules for different branch patterns
- Grant bypass to GitHub Apps (not possible with classic protection)
- Apply rules across multiple repositories in an organization