How to fix remote: error: GH006: Protected branch update failed - must use a merge queue in Git

The proper way to merge when a merge queue is required is to add your PR to the queue:

Via GitHub Web Interface:

1. Navigate to your pull request on GitHub
2. Ensure all required status checks have passed
3. Click the "Merge when ready" button (not a regular merge button)
4. Confirm by clicking "Confirm merge when ready"

GitHub will automatically add your PR to the queue once it has the required approvals and status checks.

Via GitHub CLI:

# Add a pull request to the merge queue
gh pr merge <pr-number>

# Or for the current branch's PR
gh pr merge

When the target branch requires a merge queue, gh pr merge automatically adds the PR to the queue instead of merging directly.

What happens next:
- Your PR enters the queue in FIFO (first-in-first-out) order
- GitHub creates a temporary branch to validate your changes against the latest base
- Once all checks pass and your turn comes, GitHub merges automatically

If your PR was added to the queue but isn't merging, check the status:

View the merge queue:

1. Go to your repository on GitHub
2. Click the "Pull requests" tab
3. Click the "Merge queue" link (below the list of PRs)
4. View all PRs currently in the queue and their status

Common reasons PRs are removed from the queue:

- Failed CI/status checks - Fix the failing checks and re-add to queue
- Merge conflicts - Rebase your branch and re-add to queue
- Timeout - CI took too long; check workflow efficiency
- Branch protection conflicts - Verify all requirements are met

Re-add to queue after fixing issues:

# After fixing issues, update your branch
git fetch origin
git rebase origin/main
git push --force-with-lease

# Then re-add to queue via CLI
gh pr merge

Check the PR timeline for the specific reason your PR was removed from the queue.

If you're using GitHub Actions, your workflows must be configured to work with merge queues:

Add the merge_group event trigger:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  merge_group:  # Required for merge queue support
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test

Important considerations:

1. Use the same job names - The merge queue workflow must have the same job names as your PR workflow so branch protection rules recognize them

2. Handle the temporary branch - The merge queue creates branches with prefix gh-readonly-queue/{base_branch}

3. Update third-party CI - If using external CI providers, configure them to recognize merge queue branches:

# Example for CircleCI
workflows:
  build:
    jobs:
      - test:
          filters:
            branches:
              only:
                - main
                - /gh-readonly-queue\/main\/.*/

Automated release tools like semantic-release often fail with this error because they try to push directly to protected branches:

Option 1: Use a bypass token with appropriate permissions

Create a personal access token (PAT) or GitHub App with permission to bypass branch protection:

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

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

      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Option 2: Add release bot to bypass list

1. Go to Settings > Branches > Branch protection rules
2. Edit the rule for your protected branch
3. Under "Allow specified actors to bypass required pull requests"
4. Add your release bot user or GitHub App

Option 3: Use GitHub App token

- uses: actions/create-github-app-token@v1
  id: app-token
  with:
    app-id: ${{ vars.RELEASE_APP_ID }}
    private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}

- uses: actions/checkout@v4
  with:
    token: ${{ steps.app-token.outputs.token }}

Note: Bypassing merge queue should only be used for trusted automation, not regular development work.

If merge queue isn't appropriate for your workflow, administrators can modify the settings:

To disable merge queue requirement:

1. Go to Settings > Branches in your repository
2. Click Edit next to the branch protection rule
3. Uncheck "Require merge queue"
4. Click Save changes

To allow specific users/apps to bypass:

1. In branch protection settings, find "Allow specified actors to bypass required pull requests"
2. Add users, teams, or apps that should be able to push directly
3. Save changes

Using Repository Rulesets (newer method):

1. Go to Settings > Rules > Rulesets
2. Create or edit a ruleset for your branch
3. Under "Require a pull request before merging", configure merge queue settings
4. Add bypass actors if needed

Warning: If you migrated from branch protection rules to rulesets and deleted the original protection rule, the merge queue might have been removed. You may need to:

1. Re-add the branch protection rule to recreate the merge queue
2. Or configure merge queue in the ruleset settings

Caution: Disabling merge queue on high-traffic branches can lead to merge conflicts and broken builds.

When your CI/CD pipeline encounters this error, update it to work with merge queues:

For pushing commits (e.g., version bumps):

Instead of pushing directly, create a PR and use the merge queue:

# GitHub Actions example
- name: Create Pull Request
  uses: peter-evans/create-pull-request@v6
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    commit-message: "chore: bump version"
    title: "chore: bump version to ${{ env.NEW_VERSION }}"
    branch: version-bump-${{ github.run_id }}
    base: main

# Then add to merge queue
- name: Enable auto-merge
  run: gh pr merge --auto --squash
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

For force-push scenarios:

Force pushing to protected branches with merge queues is typically blocked. Alternatives:

1. Create a new branch and PR instead of force pushing
2. Request admin bypass for exceptional cases
3. Temporarily disable protection (not recommended for production)

For tag-based releases:

Tags can usually be pushed without going through merge queue:

# Tags are typically not affected by merge queue
git tag v1.0.0
git push origin v1.0.0

However, some branch protection rules may also restrict tag creation. Check your repository settings.

Knowing the available configuration options helps troubleshoot issues:

Merge method:
- Merge commit
- Squash and merge
- Rebase and merge

Build concurrency (1-100):
Controls how many PRs can have their CI running simultaneously.

Merge limits:
- Minimum PRs to merge - Queue waits until this many PRs are ready
- Maximum PRs to merge - Batches PRs together for efficiency
- Wait timeout - How long to wait for minimum before merging anyway

Status check timeout:
How long to wait for CI before removing PR from queue.

Example configuration for a busy repository:

Merge method: Squash and merge
Build concurrency: 5
Minimum PRs to merge: 1
Maximum PRs to merge: 10
Wait for minimum: 5 minutes
Status check timeout: 60 minutes

For smaller teams or simpler workflows:

Consider whether you actually need a merge queue:
- If you have <5 PRs per day, regular merging might be sufficient
- If you rarely have merge conflicts, merge queue overhead may not be worth it
- If your CI is slow, merge queue can significantly delay merges