GitHub Actions "Pull request is not mergeable" (auto-merge)

By Kaveh Alemi·Latchkey

Enabling auto-merge or merging via the API only succeeds when the PR is in a mergeable state. Conflicts, required-but-unfinished checks, or unmet branch protection rules return a not-mergeable error.

What this error means

An auto-merge/merge step fails reporting the pull request is not mergeable, even though the workflow expects to merge it.

Error: Pull request is not mergeable (405).

Common causes

Required checks not yet passing

Branch protection requires status checks that have not completed.

Merge conflicts or review requirements

Conflicts or unmet review/approval rules block the merge.

How to fix it

Use auto-merge and satisfy protection

1. Enable auto-merge so GitHub merges once all required checks pass.
2. Ensure the workflow has the permissions to enable auto-merge.
3. Resolve conflicts and satisfy required reviews/approvals.

permissions:
  contents: write
  pull-requests: write
steps:
  - run: gh pr merge "${{ github.event.pull_request.number }}" --auto --squash
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

How to prevent it

• Prefer --auto so merges wait for required checks instead of failing.
• Keep branch protection rules and workflow expectations aligned.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions