Attempting to push directly to a protected branch instead of using a pull request (most common) CI/CD workflow lacks bypass permissions for the protected branch GitHub Actions using the default GITHUB_TOKEN which cannot bypass protection rules

Is the "GH006" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

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

GitBEGINNERMEDIUMUpdated Dec 6, 2025· 257 views

This error occurs when you try to push directly to a protected branch on GitHub. Branch protection rules require changes to go through pull requests with reviews and passing status checks.

Quick fix

Fixes GH006

# 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

Create a pull request instead of pushing directly
Check branch protection settings
Allow specific users to bypass (if appropriate)
Configure CI/CD with proper bypass permissions

git — error

$# 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
remote: error: GH006: Protected branch update failed for refs/heads/main

What this error means

When you push to a GitHub repository and receive the GH006 error, it means the target branch has protection rules enabled that prevent direct pushes. GitHub's branch protection is a feature designed to enforce code quality and team collaboration by requiring: - Pull requests instead of direct commits - Passing CI/CD status checks - Required code reviews from designated reviewers - Signed commits or linear history This error is GitHub doing its job—protecting your codebase from accidental or unauthorized changes. The `refs/heads/main` in the error message indicates which branch triggered the protection (commonly main, master, or release branches). This error commonly appears when: - Developers forget they're working on a protected branch - CI/CD pipelines try to push commits directly (like version bumps or changelog updates) - Git hooks or automation attempt to push without proper authentication - New team members aren't familiar with the repository's workflow

Typical symptoms

Git push fails immediately with 'remote: error: GH006' message
CI/CD pipeline fails during push step to main or release branch
Error message says 'Protected branch update failed'
Push worked before but now fails (protection was recently enabled)
Release automation tools like semantic-release or release-it fail
Force push attempts are also rejected

Common causes

Attempting to push directly to a protected branch instead of using a pull request (most common)
CI/CD workflow lacks bypass permissions for the protected branch
GitHub Actions using the default GITHUB_TOKEN which cannot bypass protection rules
Personal access token (PAT) lacks the required permissions
User account is not in the list of allowed bypass actors
Force push is attempted on a branch where force push is disabled
Repository settings changed and added protection to a previously unprotected branch

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

1Create a pull request instead of pushing directly

The standard solution is to use a pull request workflow:

bash

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

2Check branch protection settings

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"

3Allow specific users to bypass (if appropriate)

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.

4Configure CI/CD with proper bypass permissions

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:

yaml

- 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

5Create a machine user for automation

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:

yaml

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

- name: Push changes
  run: |
    git config user.name "build-bot"
    git config user.email "build-bot@yourorg.com"
    git push origin main

6Use GitHub Rulesets for more granular control

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

Advanced notes

### Why Not Just Disable Protection?

While temporarily disabling branch protection will let you push, this defeats the purpose of having protection in the first place. It opens a window where anyone can push directly, including malicious actors if your repo is compromised.

### Default GITHUB_TOKEN Limitations

The GITHUB_TOKEN provided by GitHub Actions has intentional limitations—it cannot bypass branch protection rules even with contents: write permission. This is a security feature. If Actions could bypass protection, a compromised workflow could push malicious code directly.

### Force Push Considerations

Protected branches typically have force push disabled. If you need to rewrite history (e.g., after a rebase):

1. This generally should go through a PR
2. Or, temporarily enable force push in Settings (not recommended)
3. Or, grant specific users force push bypass (Settings > Branches > "Allow force pushes")

### GitLab vs GitHub

This error is specific to GitHub. GitLab has similar protection but different error messages ("You are not allowed to push code to protected branches").

### Semantic-Release and Similar Tools

Tools like semantic-release need to push version commits and tags. Use one of these approaches:

1. Use a PAT with bypass permissions
2. Configure the tool to create a PR instead of pushing directly
3. Use a GitHub App with bypass permissions

Frequently asked questions

What does "GH006" mean?: When you push to a GitHub repository and receive the GH006 error, it means the target branch has protection rules enabled that prevent direct pushes. GitHub's branch protection is a feature designed to enforce code quality and team collaboration by requiring: - Pull requests instead of direct commits - Passing CI/CD status checks - Required code reviews from designated reviewers - Signed commits or linear history This error is GitHub doing its job—protecting your codebase from accidental or unauthorized changes. The refs/heads/main in the error message indicates which branch triggered the protection (commonly main, master, or release branches).
How do I fix "GH006"?: This error occurs when you try to push directly to a protected branch on GitHub. Branch protection rules require changes to go through pull requests with reviews and passing status checks.
What causes "GH006"?: Attempting to push directly to a protected branch instead of using a pull request (most common) CI/CD workflow lacks bypass permissions for the protected branch GitHub Actions using the default GITHUB_TOKEN which cannot bypass protection rules
Is the "GH006" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Git Official Documentation
📖
About protected branches - GitHub Docs(Official Docs)
📖
About rulesets - GitHub Docs(Official Docs)
💬
GH006: Protected branch update failed - Stack Overflow(Stack Overflow)
📝
How to resolve GH006 Protected Branch Update Failed
📝
GitHub Action Workflow Protected branch update failed
🐙
Protected branch update failed - semantic-release issue(GitHub)