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.
textGraphQL: 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:
textGraphQL: ["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:
bashgh 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:
bashgh 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:
bashmkdir -p .github/workflows
yamlname: 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:
bashgit 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:
bashgh 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:
yamlname: 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:
bashgh 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:
bashgh 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:
- Pull Request B’s auto-merge status does not trigger.
- GitHub marks Pull Request B as needing an update to its base branch.
- 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:
bashgh 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:
textGraphQL: GitHub Actions is not permitted to create or approve pull requests (enablePullRequestAutoMerge)
To fix this:
- Go to repository Settings > Actions > General.
- Scroll to Workflow permissions.
- 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 }}