Bash

Fix GitHub CLI Auto Merge Failures and Branch Protection Locks

You run gh pr merge --auto --squash on an open pull request, but the command fails immediately with an HTTP 405 error or sits in GitHub Actions forever without auto-merging even after your test suite passes.

text
GraphQL: Pull request is not mergeable (mergePullRequest)
gh: Pull request #14 is not mergeable: [Merge conflict detected, Base branch was modified, or Merge queue enabled]

Or you see this variation when attempting to set auto-merge through the GitHub CLI:

text
GraphQL: ["Pull request is not mergeable", "Auto merge is not allowed for this repository"]

Why this happens

The GitHub auto-merge feature looks simple on paper, but it operates under a strict set of interlocking conditions. If any single condition fails, GitHub’s API rejects the merge request outright or silently leaves the pull request open indefinitely.

The failure usually stems from three distinct problems:

First, auto-merge must be explicitly enabled at the repository level. It is disabled by default on new repositories.

Second, auto-merge requires branch protection rules or a repository ruleset targeting the base branch. If the base branch has no required reviews, no required status checks, or no merge queue defined, GitHub does not permit auto-merge. The API views auto-merge as an instruction to merge once requirements are met. If there are no requirements to meet, GitHub expects an immediate merge instead. If your CLI command attempts to enable auto-merge on an unprotected branch, the GraphQL mutation fails.

Third, the default GITHUB_TOKEN permissions in GitHub Actions often lack write permissions for pull requests. When a CI bot or a script inside a workflow attempts to run gh pr merge --auto, it hits a permission wall because pull request read and write access is restricted on standard repositories unless broadened.

Here is how to configure a repository, write a clean GitHub Actions workflow, and use the GitHub CLI to handle auto-merging reliably.

Fix repository settings and branch protection

You must ensure auto-merge is turned on in the repository settings and that your base branch has explicit protections.

Run these GitHub CLI commands using an administrative token to turn on auto-merge and verify the setting:

bash
gh repo edit --enable-auto-merge

Next, ensure your target branch (usually main) has status checks enabled. Create or update a branch protection rule using gh api. The following command sets up a protection rule requiring a check named test to pass before merging:

bash
gh api \
  --method PUT \
  -H "Accept: application/vnd.github+json" \
  /repos/:owner/:repo/branches/main/protection \
  --input - <<EOF
{
  "required_status_checks": {
    "strict": true,
    "contexts": ["test"]
  },
  "enforce_admins": false,
  "required_pull_request_reviews": null,
  "restrictions": null
}
EOF

If you prefer to configure this via GitHub’s web interface, navigate to Settings > General, check the box labeled Allow auto-merge, then go to Settings > Branches and add a branch protection rule with at least one required status check.

Minimal GitHub Actions CI configuration

The required check name in your branch protection rule must match the exact name of the job in your workflow file, not the name of the workflow itself.

Save this workflow file in .github/workflows/ci.yml. It runs tests, reports status under the exact context name test, and handles pull request events correctly:

bash
mkdir -p .github/workflows
yaml
name: CI

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  test:
    name: test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run test suite
        run: |
          echo "Running test suite..."
          # Replace with your test command, e.g., cargo test, npm test, pytest
          exit 0

Notice the job name is test. This matches the context "contexts": ["test"] configured in the branch protection rule above.

Creating and auto-merging pull requests via GitHub CLI

When creating and enabling auto-merge locally using the GitHub CLI, you must run two steps if you want the pull request to automatically squash-merge as soon as CI passes.

Create the branch, make a change, push it, and open the pull request:

bash
git checkout -b fix-auth-token
touch dummy.txt
git add dummy.txt
git commit -m "fix: update token parsing"
git push -u origin fix-auth-token

gh pr create \
  --title "fix: update token parsing" \
  --body "Resolves parser failures on empty tokens." \
  --base main

Once the pull request is open, tell GitHub to auto-merge it when the checks finish:

bash
gh pr merge --auto --squash

You can combine these into your branch workflow. If you want a complete Bash script that automates branch creation, commits, PR generation, and registers the auto-merge instruction, use this:

bash
#!/usr/bin/env bash
set -euo pipefail

BRANCH_NAME="update-deps-$(date +%s)"
COMMIT_MSG="chore: automated dependency updates"

git checkout -b "$BRANCH_NAME"
echo "build-cache" >> .gitignore
git add .gitignore
git commit -m "$COMMIT_MSG"
git push -u origin "$BRANCH_NAME"

PR_URL=$(gh pr create --title "$COMMIT_MSG" --body "Automated changes." --base main)
echo "Created PR: $PR_URL"

gh pr merge "$PR_URL" --auto --squash
echo "Auto-merge enabled for $PR_URL"

Automating auto-merge inside a GitHub Action

A common requirement is having a GitHub Action enable auto-merge on pull requests opened by Dependabot or other internal automation.

This requires broader workflow permissions. By default, the GITHUB_TOKEN does not have permission to enable auto-merge or modify pull requests.

Add this workflow file at .github/workflows/auto-merge.yml:

yaml
name: Auto Merge PRs

on:
  pull_request:
    types:
      - opened
      - reopened

permissions:
  contents: write
  pull-requests: write

jobs:
  enable-merge:
    runs-on: ubuntu-latest
    if: github.actor == 'dependabot[bot]' || contains(github.event.pull_request.labels.*.name, 'automerge')
    steps:
      - name: Enable auto-merge on the pull request
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_URL: ${{ github.event.pull_request.html_url }}

Note the permissions block. If pull-requests: write and contents: write are missing, the command fails with an authorization error.

Verification

To verify that the auto-merge setup works correctly, inspect the PR using the CLI while the CI job is running:

bash
gh pr view --json autoMergeRequest,statusCheckRollup

If auto-merge is active, the JSON output will display an autoMergeRequest object with the target merge method:

text
{
  "autoMergeRequest": {
    "enabledAt": "2024-10-24T18:32:05Z",
    "enabledBy": {
      "login": "octocat"
    },
    "mergeMethod": "SQUASH"
  },
  "statusCheckRollup": [
    {
      "context": "test",
      "state": "PENDING"
    }
  ]
}

Wait until the test job completes. Query the pull request state again:

bash
gh pr view --json state,mergedAt,mergedBy

The output should confirm the pull request has closed and merged:

text
{
  "mergedAt": "2024-10-24T18:33:12Z",
  "mergedBy": {
    "login": "octocat"
  },
  "state": "MERGED"
}

Edge case 1: Stale base branch with strict status checks

When your branch protection has "strict": true (in the web interface: Require branches to be up to date before merging), the auto-merge engine requires the pull request branch to include the latest commit from main.

If Pull Request A merges into main while Pull Request B is running CI:

  1. Pull Request B’s auto-merge status does not trigger.
  2. GitHub marks Pull Request B as needing an update to its base branch.
  3. The merge halts.

To solve this, configure the repository to allow automatic branch updates, or instruct the GitHub CLI to update the branch before setting auto-merge:

bash
gh repo edit --enable-auto-merge
gh api \
  --method PATCH \
  -H "Accept: application/vnd.github+json" \
  /repos/:owner/:repo \
  -F allow_auto_merge=true \
  -F allow_update_branch=true

With allow_update_branch set to true, GitHub automatically merges main into the head branch of the pull request if it falls behind, runs the CI checks on the updated code, and then merges.

Edge case 2: Auto-merge blocked by GITHUB_TOKEN restrictions

In many enterprise or newly created personal organizations, GitHub applies an organization-level security setting: Allow GitHub Actions to create and approve pull requests.

If this setting is turned off, any gh pr merge --auto call inside a workflow using GITHUB_TOKEN fails with this error:

text
GraphQL: GitHub Actions is not permitted to create or approve pull requests (enablePullRequestAutoMerge)

To fix this:

  1. Go to repository Settings > Actions > General.
  2. Scroll to Workflow permissions.
  3. Check the box for Allow GitHub Actions to create and approve pull requests.

If your organization manages this globally and will not allow workflow-managed PR merges, you cannot use the default GITHUB_TOKEN. You must generate a personal access token (fine-grained or classic with repo scope) or use a GitHub App token with pull_requests:write and contents:write permissions, and pass that token to the step:

yaml
      - name: Enable auto-merge with App Token
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          GH_TOKEN: ${{ secrets.CUSTOM_MERGE_PAT }}
          PR_URL: ${{ github.event.pull_request.html_url }}

More in Bash