Agent GitHub Merge Queue and Auto-Merge State

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

GitHub merge queue and auto-merge state tell agents whether a pull request is waiting on policy, queue validation, permissions, or missing merge-group CI rather than a code defect.

## Core Explanation

An agent should treat "not mergeable" as a state to diagnose, not a reason to edit code blindly. Auto-merge may be waiting for reviews or status checks, while merge queue may create a temporary merge group SHA whose checks differ from the pull request head SHA.

Useful evidence includes base branch, queue position, merge method, merge-group branch or SHA, required check names, auto-merge enabled state, last actor who pushed to the head branch, repository write permission, and whether workflows include the `merge_group` trigger required for queued validation.

## Source-Mapped Facts

- GitHub auto-merge documentation says a pull request with auto-merge enabled will merge automatically when required reviews are met and required status checks pass. ([source](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request))
- GitHub auto-merge documentation says auto-merge is disabled if someone without write permission pushes new changes to the pull request head branch or switches the base branch. ([source](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request))
- GitHub merge queue documentation says CI must trigger and report on merge group events when a merge queue is required. ([source](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue))
- GitHub merge queue documentation says the merge queue creates temporary branches with a special prefix to validate pull request changes. ([source](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue))

## Further Reading

- [GitHub Automatically Merging a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request)
- [GitHub Managing a Merge Queue](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)
- [GitHub Actions merge_group Event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#merge_group)